castle-web-cli 0.4.229 → 0.4.231

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (259) hide show
  1. package/dist/agent-prompts.d.ts +2 -0
  2. package/dist/agent-prompts.js +16 -8
  3. package/dist/agent.d.ts +2 -0
  4. package/dist/agent.js +21 -21
  5. package/dist/api.d.ts +28 -2
  6. package/dist/api.js +74 -16
  7. package/dist/castle-host/host.d.ts +91 -0
  8. package/dist/castle-host/host.js +860 -3
  9. package/dist/castleJson.d.ts +44 -0
  10. package/dist/castleJson.js +131 -0
  11. package/dist/check.js +27 -1
  12. package/dist/contentPack.d.ts +49 -0
  13. package/dist/contentPack.js +273 -0
  14. package/dist/devExperiments.d.ts +21 -0
  15. package/dist/devExperiments.js +139 -0
  16. package/dist/devHub.d.ts +55 -0
  17. package/dist/devHub.js +187 -0
  18. package/dist/devSaveStorage.d.ts +36 -0
  19. package/dist/devSaveStorage.js +469 -0
  20. package/dist/devSessionChild.js +25 -13
  21. package/dist/devSessionServer.d.ts +14 -1
  22. package/dist/devSessionServer.js +237 -46
  23. package/dist/devSessionStorage.d.ts +9 -0
  24. package/dist/devSessionStorage.js +66 -1
  25. package/dist/experimentAssignment.d.ts +15 -0
  26. package/dist/experimentAssignment.js +41 -0
  27. package/dist/importCheckHook.d.ts +40 -0
  28. package/dist/importCheckHook.js +171 -0
  29. package/dist/importRegression.d.ts +15 -0
  30. package/dist/importRegression.js +100 -0
  31. package/dist/importTrust.d.ts +2 -0
  32. package/dist/importTrust.js +27 -0
  33. package/dist/importUpdateHook.d.ts +18 -0
  34. package/dist/importUpdateHook.js +31 -8
  35. package/dist/importUpdateHookRunner.js +19 -7
  36. package/dist/imports.d.ts +16 -0
  37. package/dist/imports.js +141 -31
  38. package/dist/index.js +3 -1
  39. package/dist/init.d.ts +3 -0
  40. package/dist/init.js +126 -9
  41. package/dist/install.js +4 -1
  42. package/dist/localPaths.js +4 -0
  43. package/dist/login.js +2 -2
  44. package/dist/platformDoc.js +3 -8
  45. package/dist/playPagePolicy.js +3 -1
  46. package/dist/remix.js +5 -0
  47. package/dist/routerTaskReport.d.ts +28 -0
  48. package/dist/routerTaskReport.js +56 -0
  49. package/dist/save-deck.d.ts +18 -0
  50. package/dist/save-deck.js +142 -6
  51. package/dist/serve.d.ts +8 -0
  52. package/dist/serve.js +99 -14
  53. package/dist/serverBundle.d.ts +1 -1
  54. package/dist/serverBundle.js +5 -1
  55. package/dist/webSourceSync.d.ts +2 -0
  56. package/dist/webSourceSync.js +2 -0
  57. package/kits/base/CLAUDE.md +2 -3
  58. package/kits/base/castle.json +1 -1
  59. package/kits/base/sdk/README.md +406 -53
  60. package/kits/base/sdk/agent.js +4 -4
  61. package/kits/base/sdk/avatar.d.ts +12 -0
  62. package/kits/base/sdk/avatar.js +23 -0
  63. package/kits/base/sdk/castle.d.ts +9 -0
  64. package/kits/base/sdk/castle.js +5 -0
  65. package/kits/base/sdk/commands.d.ts +223 -0
  66. package/kits/base/sdk/commands.js +16 -0
  67. package/kits/base/sdk/context.d.ts +6 -0
  68. package/kits/base/sdk/experiments.d.ts +15 -0
  69. package/kits/base/sdk/experiments.js +83 -0
  70. package/kits/base/sdk/hub.d.ts +85 -0
  71. package/kits/base/sdk/hub.js +107 -0
  72. package/kits/base/sdk/multiplayer.d.ts +45 -1
  73. package/kits/base/sdk/multiplayer.js +158 -8
  74. package/kits/base/sdk/save.d.ts +197 -0
  75. package/kits/base/sdk/save.js +525 -0
  76. package/kits/base/sdk/saveCoordinator.d.ts +39 -0
  77. package/kits/base/sdk/saveCoordinator.js +252 -0
  78. package/kits/base/sdk/server/hub.d.ts +169 -0
  79. package/kits/base/sdk/server/hub.js +125 -0
  80. package/kits/base/sdk/server/platformHandle.d.ts +42 -1
  81. package/kits/base/sdk/server/storage.d.ts +58 -4
  82. package/kits/base/sdk/server/storage.js +25 -5
  83. package/kits/base/sdk/server/wrapper.d.ts +36 -2
  84. package/kits/base/sdk/server/wrapper.js +92 -11
  85. package/kits/base/sdk/store.d.ts +3 -2
  86. package/kits/base/sdk/store.js +5 -0
  87. package/kits/base/sdk/transport.d.ts +2 -1
  88. package/kits/base/sdk/transport.js +13 -1
  89. package/kits/hub-game/.prettierrc +5 -0
  90. package/kits/hub-game/CLAUDE.md +149 -0
  91. package/kits/hub-game/blueprints/avatar-0.scene +28 -0
  92. package/kits/hub-game/blueprints/avatar-1.scene +28 -0
  93. package/kits/hub-game/blueprints/avatar-2.scene +28 -0
  94. package/kits/hub-game/blueprints/avatar-3.scene +28 -0
  95. package/kits/hub-game/blueprints/bean/avatar-0.scene +28 -0
  96. package/kits/hub-game/blueprints/bean/avatar-1.scene +28 -0
  97. package/kits/hub-game/blueprints/bean/avatar-2.scene +28 -0
  98. package/kits/hub-game/blueprints/bean/avatar-3.scene +28 -0
  99. package/kits/hub-game/blueprints/blocky/avatar-0.scene +28 -0
  100. package/kits/hub-game/blueprints/blocky/avatar-1.scene +28 -0
  101. package/kits/hub-game/blueprints/blocky/avatar-2.scene +28 -0
  102. package/kits/hub-game/blueprints/blocky/avatar-3.scene +28 -0
  103. package/kits/hub-game/blueprints/pixel/avatar-0.scene +28 -0
  104. package/kits/hub-game/blueprints/pixel/avatar-1.scene +28 -0
  105. package/kits/hub-game/blueprints/pixel/avatar-2.scene +28 -0
  106. package/kits/hub-game/blueprints/pixel/avatar-3.scene +28 -0
  107. package/kits/hub-game/castle.json +96 -0
  108. package/kits/hub-game/code/client/attention.js +133 -0
  109. package/kits/hub-game/code/client/avatar.js +288 -0
  110. package/kits/hub-game/code/client/cabinets.js +90 -0
  111. package/kits/hub-game/code/client/chat.js +135 -0
  112. package/kits/hub-game/code/client/chrome.js +1035 -0
  113. package/kits/hub-game/code/client/doorFrame.js +15 -0
  114. package/kits/hub-game/code/client/firstJoin.js +14 -0
  115. package/kits/hub-game/code/client/grab.js +376 -0
  116. package/kits/hub-game/code/client/hookLayer.js +236 -0
  117. package/kits/hub-game/code/client/idle.js +326 -0
  118. package/kits/hub-game/code/client/keys.js +48 -0
  119. package/kits/hub-game/code/client/pack.js +232 -0
  120. package/kits/hub-game/code/client/packFormat.js +397 -0
  121. package/kits/hub-game/code/client/say.js +127 -0
  122. package/kits/hub-game/code/client/sha256.js +80 -0
  123. package/kits/hub-game/code/client/sound.js +147 -0
  124. package/kits/hub-game/code/client/state.js +143 -0
  125. package/kits/hub-game/code/client/talk.js +233 -0
  126. package/kits/hub-game/code/client/tiers.js +480 -0
  127. package/kits/hub-game/code/client/together.js +440 -0
  128. package/kits/hub-game/code/client/wear.js +149 -0
  129. package/kits/hub-game/code/server/actors.js +627 -0
  130. package/kits/hub-game/code/server/blocks.js +103 -0
  131. package/kits/hub-game/code/server/cabinets.js +309 -0
  132. package/kits/hub-game/code/server/game.js +137 -0
  133. package/kits/hub-game/code/server/grab.js +248 -0
  134. package/kits/hub-game/code/server/history.js +96 -0
  135. package/kits/hub-game/code/server/hub.js +1998 -0
  136. package/kits/hub-game/code/server/idle.js +412 -0
  137. package/kits/hub-game/code/server/index.js +64 -0
  138. package/kits/hub-game/code/server/labels.js +59 -0
  139. package/kits/hub-game/code/server/manifest.js +554 -0
  140. package/kits/hub-game/code/server/npcs.js +733 -0
  141. package/kits/hub-game/code/server/party.js +439 -0
  142. package/kits/hub-game/code/server/place.js +43 -0
  143. package/kits/hub-game/code/server/say.js +83 -0
  144. package/kits/hub-game/code/server/wear.js +142 -0
  145. package/kits/hub-game/code/systems/hub.js +2347 -0
  146. package/kits/hub-game/docs/content-pack.md +151 -0
  147. package/kits/hub-game/docs/contract.md +1209 -0
  148. package/kits/hub-game/docs/style.md +137 -0
  149. package/kits/hub-game/drawings/blocky/castle-eye.sprite +58 -0
  150. package/kits/hub-game/drawings/blocky/dash.sprite +59 -0
  151. package/kits/hub-game/drawings/blocky/pom.sprite +59 -0
  152. package/kits/hub-game/drawings/blocky/tabby.sprite +59 -0
  153. package/kits/hub-game/drawings/pixel/castle-arm.sprite +13 -0
  154. package/kits/hub-game/drawings/pixel/castle-body.sprite +23 -0
  155. package/kits/hub-game/drawings/pixel/castle-leg.sprite +12 -0
  156. package/kits/hub-game/drawings/pixel/kai-arm.sprite +14 -0
  157. package/kits/hub-game/drawings/pixel/kai-head.sprite +24 -0
  158. package/kits/hub-game/drawings/pixel/kai-leg.sprite +15 -0
  159. package/kits/hub-game/drawings/pixel/kai-torso.sprite +18 -0
  160. package/kits/hub-game/drawings/pixel/mimi-arm.sprite +13 -0
  161. package/kits/hub-game/drawings/pixel/mimi-head.sprite +23 -0
  162. package/kits/hub-game/drawings/pixel/mimi-leg.sprite +15 -0
  163. package/kits/hub-game/drawings/pixel/mimi-torso.sprite +18 -0
  164. package/kits/hub-game/drawings/pixel/nox-arm.sprite +13 -0
  165. package/kits/hub-game/drawings/pixel/nox-head.sprite +21 -0
  166. package/kits/hub-game/drawings/pixel/nox-leg.sprite +14 -0
  167. package/kits/hub-game/drawings/pixel/nox-torso.sprite +18 -0
  168. package/kits/hub-game/eslint.config.js +20 -0
  169. package/kits/hub-game/fonts.generated.js +9 -0
  170. package/kits/hub-game/index.html +22 -0
  171. package/kits/hub-game/main.jsx +6 -0
  172. package/kits/hub-game/models/avatar-0.pxmodel +21 -0
  173. package/kits/hub-game/models/avatar-1.pxmodel +24 -0
  174. package/kits/hub-game/models/avatar-2.pxmodel +27 -0
  175. package/kits/hub-game/models/avatar-3.pxmodel +22 -0
  176. package/kits/hub-game/models/bean/avatar-0.pxmodel +19 -0
  177. package/kits/hub-game/models/bean/avatar-1.pxmodel +24 -0
  178. package/kits/hub-game/models/bean/avatar-2.pxmodel +22 -0
  179. package/kits/hub-game/models/bean/avatar-3.pxmodel +24 -0
  180. package/kits/hub-game/models/blocky/avatar-0.pxmodel +21 -0
  181. package/kits/hub-game/models/blocky/avatar-1.pxmodel +30 -0
  182. package/kits/hub-game/models/blocky/avatar-2.pxmodel +28 -0
  183. package/kits/hub-game/models/blocky/avatar-3.pxmodel +27 -0
  184. package/kits/hub-game/models/pixel/avatar-0.pxmodel +24 -0
  185. package/kits/hub-game/models/pixel/avatar-1.pxmodel +16 -0
  186. package/kits/hub-game/models/pixel/avatar-2.pxmodel +19 -0
  187. package/kits/hub-game/models/pixel/avatar-3.pxmodel +23 -0
  188. package/kits/hub-game/package-lock.json +365 -0
  189. package/kits/hub-game/package.json +32 -0
  190. package/kits/hub-game/scenes/main.scene +318 -0
  191. package/kits/hub-game/scripts/check.mjs +339 -0
  192. package/kits/hub-game/scripts/fixtures/sdk-stub.mjs +3 -0
  193. package/kits/hub-game/scripts/gen-avatars-bean.mjs +748 -0
  194. package/kits/hub-game/scripts/gen-avatars-blocky.mjs +607 -0
  195. package/kits/hub-game/scripts/gen-avatars-pixel.mjs +771 -0
  196. package/kits/hub-game/scripts/gen-avatars.mjs +621 -0
  197. package/kits/hub-game/scripts/pack.mjs +192 -0
  198. package/kits/hub-game/scripts/test-actors.mjs +666 -0
  199. package/kits/hub-game/scripts/test-attention.mjs +103 -0
  200. package/kits/hub-game/scripts/test-avatar.mjs +472 -0
  201. package/kits/hub-game/scripts/test-ban-join.mjs +194 -0
  202. package/kits/hub-game/scripts/test-blocks.mjs +351 -0
  203. package/kits/hub-game/scripts/test-chat.mjs +98 -0
  204. package/kits/hub-game/scripts/test-classic.mjs +590 -0
  205. package/kits/hub-game/scripts/test-door-jump.mjs +131 -0
  206. package/kits/hub-game/scripts/test-door.mjs +56 -0
  207. package/kits/hub-game/scripts/test-grab-client.mjs +328 -0
  208. package/kits/hub-game/scripts/test-grab.mjs +331 -0
  209. package/kits/hub-game/scripts/test-hub-ops.mjs +835 -0
  210. package/kits/hub-game/scripts/test-hub-trip.mjs +1518 -0
  211. package/kits/hub-game/scripts/test-idle.mjs +518 -0
  212. package/kits/hub-game/scripts/test-interest.mjs +413 -0
  213. package/kits/hub-game/scripts/test-keys.mjs +50 -0
  214. package/kits/hub-game/scripts/test-manifest.mjs +270 -0
  215. package/kits/hub-game/scripts/test-no-forms.mjs +16 -0
  216. package/kits/hub-game/scripts/test-npcs.mjs +724 -0
  217. package/kits/hub-game/scripts/test-pack.mjs +424 -0
  218. package/kits/hub-game/scripts/test-party.mjs +369 -0
  219. package/kits/hub-game/scripts/test-say.mjs +149 -0
  220. package/kits/hub-game/scripts/test-tiers.mjs +666 -0
  221. package/kits/hub-game/scripts/test-together.mjs +215 -0
  222. package/kits/hub-game/theme.style +3 -0
  223. package/kits/multiplayer-3d/castle.json +5 -5
  224. package/kits/multiplayer-3d/code/client/avatars.js +101 -1
  225. package/kits/multiplayer-3d/code/server/players.js +4 -1
  226. package/kits/multiplayer-3d/code/server/sceneBodies.js +27 -6
  227. package/kits/multiplayer-3d/code/server/world.js +20 -7
  228. package/kits/multiplayer-3d/code/systems/multiplayer.js +222 -11
  229. package/kits/physics-2d/CLAUDE.md +2 -0
  230. package/kits/physics-2d/castle.json +2 -2
  231. package/kits/physics-2d/engine/art.js +13 -0
  232. package/kits/physics-2d/engine/assets.js +4 -2
  233. package/kits/physics-2d/engine/scene.js +117 -5
  234. package/kits/physics-2d/package.json +1 -1
  235. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +254 -0
  236. package/kits/physics-3d/CLAUDE.md +285 -1
  237. package/kits/physics-3d/behaviors/Player.jsx +74 -1
  238. package/kits/physics-3d/castle.json +3 -3
  239. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +33 -5
  240. package/kits/physics-3d/engine3d/actornode.js +253 -0
  241. package/kits/physics-3d/engine3d/artobjects.js +2 -2
  242. package/kits/physics-3d/engine3d/materials.js +29 -1
  243. package/kits/physics-3d/engine3d/nearshadows.js +600 -0
  244. package/kits/physics-3d/engine3d/unchanged.js +153 -0
  245. package/kits/physics-3d/engine3d/world3d.js +527 -5
  246. package/kits/physics-3d/package.json +1 -1
  247. package/kits/physics-3d/scripts/test-camera-follow.mjs +533 -0
  248. package/kits/physics-3d/scripts/test-near-shadows.mjs +1073 -0
  249. package/kits/physics-3d/scripts/test-static-actors.mjs +662 -0
  250. package/kits/physics-3d/scripts/test-static-passes.mjs +459 -0
  251. package/kits/physics-3d/scripts/test-static-physics.mjs +128 -0
  252. package/kits/physics-3d/systems/physics3d.js +187 -5
  253. package/kits/real-time/castle.json +2 -2
  254. package/kits/real-time/code/client/connection.js +77 -7
  255. package/kits/real-time/code/client/gameHooks.js +63 -3
  256. package/kits/real-time/code/client/messages.js +7 -0
  257. package/kits/real-time/code/server/gameHooks.js +24 -0
  258. package/kits/real-time/code/server/session.js +390 -22
  259. package/package.json +2 -2
@@ -0,0 +1,1209 @@
1
+ # The hub-game contract
2
+
3
+ **Version 1.22** (2026-10-04; v1 plus the optional additions under "Changes in
4
+ v1", each marked with the minor version that added it). Kit: `castle.hub-game` (`kits/hub-game`). Design:
5
+ `cauldron-game-server` `docs/HUB.md` (decision 3: a hub game is a kit plus a
6
+ contract). Inputs: the M0 report's Tier 0 gaps 1-9 (card
7
+ `hub-m0-town-deck-with-two-doors-scene-swap-and-p`).
8
+
9
+ A **hub game** is a deck built on `castle.hub-game` that declares a `hub` block in
10
+ its `castle.json` and ships nothing to the client but data (Tier 0): scenes,
11
+ models, blueprints, engine behaviors by name. Its server half is ordinary deck
12
+ code (`code/server/game.js`). Every hub-kit deck is a **place**; the town is the
13
+ place with the most doors.
14
+
15
+ The contract is everything a published hub game depends on. It changes only by a
16
+ version bump: a new optional field is a minor change inside the same version; a
17
+ removed or re-meant field is version 2, and the kit keeps reading version 1 decks
18
+ for as long as a published one exists (HUB.md Risks: "a contract is forever").
19
+
20
+ ## What a hub game may not do
21
+
22
+ Checked by the kit's check (`scripts/check.mjs`, run by `castle-web check` and `save-deck`) where it can be, by
23
+ curation where it cannot:
24
+
25
+ - ship client code: no `code/client/`, no `code/systems/`, no `behaviors/`, no
26
+ `*.js`/`*.jsx` outside `code/server/`, and an `index.html` that loads the kit's
27
+ entry and nothing else (Tier 0);
28
+ - ship its own player character: no `blueprints/other-player.scene`, and the
29
+ scene's `Player` actor is drawn as the platform avatar whatever its `Model`
30
+ says;
31
+ - call `Portal.open`, draw its own cosmetics or shop, or draw over the hub chrome
32
+ (it has no client code to do any of it with);
33
+ - choose where a player comes out, keep a player past `maxDurationSec`, or have a
34
+ lobby or a leave button of its own.
35
+
36
+ ## 1. The manifest: `castle.json` → `hub`
37
+
38
+ ```jsonc
39
+ "hub": {
40
+ "contract": 1, // required; the version this deck was written against
41
+ "title": "Foot Race", // ≤ 40 chars; the door cover, the result ribbon
42
+ "scene": "scenes/main.scene", // optional; the place's scene (default: editor.defaultPlayFile, then scenes/main.scene)
43
+ "minPlayers": 1, // 1..24; a pad does not fire below it
44
+ "maxPlayers": 8, // 1..24 and ≤ server.maxPlayers; one instance never holds more
45
+ "lateJoin": true, // a pad may send a player into a running instance with room
46
+ "maxDurationSec": 300, // 30..1800; the kit sends a player back when their visit reaches it
47
+ "controller": "walk", // a controller preset (§6)
48
+ "arrival": { // §5
49
+ "actor": "arrival", // id of the scene actor players arrive at (default: the Player actor's spawn)
50
+ "spread": 1.5, // metres between players arriving together (0..5, default 1.5)
51
+ "face": "actor" // "actor" (its Transform.rotationY) | "center" (toward x=0,z=0) | a number of degrees
52
+ },
53
+ "result": { // §7; omit for a place that reports no results (a town)
54
+ "outcomes": ["win", "lose", "draw"],
55
+ "score": { "unit": "ms", "better": "lower", "min": 0, "max": 600000 },
56
+ "stats": { "laps": "number", "kart": "string" }
57
+ },
58
+ "sign": { "model": "models/sign.pxmodel", "board": "score" }, // optional
59
+ "npcs": { "route": "town", "slot": "square", "turnsPerMinute": 6 }, // optional; §13
60
+ "fallY": -10, // optional (v1.1); below this a player has fallen (§5)
61
+ "grab": true, // optional (v1.3); players pick up loose objects and throw them (§6)
62
+ "idle": { "emotes": true, "seats": true, "sounds": ["sounds/jukebox.mp3"] }, // optional (v1.6); emotes, seats, the place's sounds (§6)
63
+ "nearestPlayers": 30, // optional; 1..100, how many other players each client is sent (§12)
64
+ "tiers": true, // optional (v1.21); a cheaper picture on a slow device, client only
65
+ "places": { } // optional; more places in the same deck (§3)
66
+ }
67
+ ```
68
+
69
+ | field | type | rule |
70
+ | --- | --- | --- |
71
+ | `contract` | integer | `1`. A deck naming a version the kit does not know is refused (check fails; the server logs and runs nothing). |
72
+ | `title` | string | 1-40 chars. |
73
+ | `scene` | string | a `scenes/*.scene` path the deck has. |
74
+ | `minPlayers`, `maxPlayers` | integer | `1 ≤ min ≤ max ≤ 24`; `max ≤ server.maxPlayers`. |
75
+ | `lateJoin` | boolean | default `false`. |
76
+ | `maxDurationSec` | integer | 30-1800. Default 600 for a place that declares `result`; a place that does not (a town) has no limit unless it sets one. |
77
+ | `controller` | string | a preset name the kit has (§6). |
78
+ | `arrival` | object | §5. |
79
+ | `result` | object | §7. |
80
+ | `sign` | object | `model`: a `.pxmodel` the deck has; `board`: `"score"` or a declared numeric stat. |
81
+ | `places` | object | §3. |
82
+ | `npcs` | object | §13. |
83
+ | `fallY` | number | v1.1. -25 to 50 metres; below it a player has fallen (§5). Default: none, or -20 in a scene with no ground. |
84
+ | `grab` | boolean or object | v1.3. `true`, or `{ throwSpeed, holdDistance, holdHeight }`: 1-14 m/s (default 10), 0.8-3 m (default 1.4), 0-2.5 m (default 1.2); any left out takes its default. v1.22 adds two, each optional: `reach`, 1.6-3 m, how far (flat, from the object's near side) an object is offered, and `steady`, true or false, an offer that holds through a moment at its edge (§6). Left out (or `steady: false`), neither is sent to the client nor changes anything: the place is offered, sent and drawn exactly what it was. `false` or absent: no grabbing (§6). |
85
+ | `idle` | boolean or object | v1.6. `true` (emotes and seats), or `{ emotes, seats, sounds }`: `emotes` and `seats` true or false (default false), `sounds` up to 16 different `.mp3`/`.wav`/`.m4a` paths (lower-case extensions, as the engine bundles them) of this deck that `hub.sound` may play (each at most 256 KB, 1 MB in all, checked at publish). `false`, absent or all off: none of it (§6). |
86
+ | `nearestPlayers` | integer | 1-100, default 30. Each client is sent the poses of only this many other players, the nearest (§12). |
87
+ | `tiers` | boolean | v1.21, the deck's (not a place's). `true`: each client draws a cheaper picture where the device is slow -- a weak phone GPU or 2 GB or less of memory, or frames slower than 40 ms (the median of the first 5 s after arrival, or of any 10 s after), remembered on the device for 7 days. Low has no sun shadow (the render resolution is unchanged), no decorative actors (only `Transform`/`Shape`/`Model`), and no scenery (those plus `Solid`/`Lookable`) past 30 m or NPC bodies past 20 m; doors, pads, players and anything else with gameplay are always drawn, and in a game reached through a door only the shadow changes. The Character card gains Graphics: Auto / Low / High, kept on the device; Low or High wins. Nothing changes on the wire or for other players. `false` or absent: none of it. |
88
+
89
+ Unknown keys are a check failure, not ignored: a typo in a contract field must
90
+ not publish as "no such rule".
91
+
92
+ ## 2. Where a session learns its place
93
+
94
+ **A session's server never learns its place from a client.** (M0 gap 6: the M0
95
+ town let the first client name the scene, so any client could start a session
96
+ of any of the deck's scenes.) The kit resolves the place once, from the session,
97
+ before the world is built, in this order:
98
+
99
+ 1. **`session.place`**, stamped by the host. It is the seam for ghost's door
100
+ placement: the door row (`cauldron_hub_doors`) names the destination place,
101
+ ghost puts it in the session spec, and the host hands it to the runtime
102
+ (`PlatformSessionConfig.place`). No production host stamps it yet; that is the
103
+ doors card's.
104
+ 2. **The dev serve's named key**, and only there: a session id `dev:hub.<place>.<instance>`
105
+ (the key a place mints in `hub.go`, §4) names `<place>`. This is honoured only
106
+ for a `dev:` session id, i.e. on `castle-web serve`, where every client is the
107
+ author's own. A production named key is chosen by a client and never read.
108
+ 3. Otherwise the deck's main place.
109
+
110
+ A place id the deck does not declare falls back to the main place and is logged.
111
+ `sceneFromClient` (the M0 seam in `castle.real-time`) is not used by hub decks.
112
+
113
+ ## 3. Places
114
+
115
+ A deck is one place unless it declares more:
116
+
117
+ ```jsonc
118
+ "places": {
119
+ "race": { "title": "Foot Race", "scene": "scenes/race.scene", "minPlayers": 1, "maxPlayers": 6, … },
120
+ "arena": { "title": "King of the Hill", "scene": "scenes/arena.scene", … }
121
+ }
122
+ ```
123
+
124
+ Each entry is a full place block (every field of §1 but `contract` and
125
+ `places`); the top-level fields are the main place. A place's server hooks are
126
+ `code/server/places/<id>.js` when it exists, else `code/server/game.js`. Place ids
127
+ match `[a-z][a-z0-9-]{0,23}`; `main` is reserved for the top level.
128
+
129
+ Several places in one deck is how a game's lobby has doors to its own arenas. A
130
+ door to another deck mounts that deck's **content pack** (`docs/content-pack.md`):
131
+ its client half as data, published paired with its server bundle.
132
+
133
+ ## 4. Server hooks
134
+
135
+ `castle.json` → `server.main` is `imports/castle.hub-game/code/server/index.js`.
136
+ The deck writes `code/server/game.js` (or `places/<id>.js`) with a default export
137
+ of any of these. Every hook gets `hub`, the place's context, first:
138
+
139
+ | hook | when |
140
+ | --- | --- |
141
+ | `ready(hub)` | the world is built, before the first tick |
142
+ | `arrive(hub, group)` | players with bodies who arrived together this tick: `[{ playerId, username, userId, from, fromDeckId, near, carry }]` (`userId` v1.2: a signed-in player's user id, null for an anonymous one). `from` is the door they came in by; `near` the user id of the friend they jumped to (Join), or null; `carry.result` what they bring back from a game (§7). The kit has already placed them at the arrival (§5), and a player who jumped to a friend in this session beside that friend, facing them; a hook may place them elsewhere |
143
+ | `step(hub, dt)` | after each physics step; `dt` seconds |
144
+ | `fall(hub, playerId)` | v1.1: a player fell below the place's `fallY` (§5); place them somewhere, or the kit puts them back at the arrival |
145
+ | `carry(hub, playerId, carry)` | where the host has hub ops: what an already-arrived player brings back, when ghost's read came after the arrival window (§7) |
146
+ | `leave(hub, playerId, { userId, username })` | a player left (Back, the host's Back, a closed tab). Runs while the player is still known (v1.2): `hub.result` takes their result for the visit here, and `userId` names their storage (§14) |
147
+ | `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) |
148
+ | `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 |
149
+ | `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 |
150
+ | `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 |
151
+ | `message(hub, player, data)` | a client message that is not the kit's own. Tier 0 games have no client code, so this is for bots and tests |
152
+ | `where(hub, at)` | v1.9, a town: what the place calls the spot `at` (`{ x, y, z }`), for the People list (§5): a string of at most 40 characters ("in the square", "on Race Row"), or null. Asked only for a spot that is not on a door's pad or beside a door, which the kit words itself |
153
+ | `npcLine(hub, npc, playerId, { why, text })` | an authored line for an NPC to say to a player when its mind is not answering (§13); return a string, or null for the kit's |
154
+ | `npcContext(hub, npc, playerId)` | v1.8: what an NPC's mind should know right now while `playerId` talks to it (§13 notes): a string of at most 700 characters, or null for none. Read when the conversation opens and every second while it lasts |
155
+ | `npcHeard(hub, npc, playerId, { text })` | v1.8: a turn to an NPC's mind was admitted; `text` is the player's own words (§13), for place state a conversation may change |
156
+
157
+ `hub` carries the session, so a tick can send (M0 gap 5):
158
+
159
+ | member | what |
160
+ | --- | --- |
161
+ | `hub.session`, `hub.sim` | the Castle session and the multiplayer-3d simulation |
162
+ | `hub.place` | `{ id, title, scene, manifest }` |
163
+ | `hub.now` | simulation milliseconds |
164
+ | `hub.players()` | `[{ playerId, username, userId, at, arrivedAt }]` for players with bodies (`userId` v1.2, null for an anonymous player) |
165
+ | `hub.actorsWith(component)` | scene actors carrying a component: `[{ id, props, t, shape, body }]`: `props` the component's, `t` the Transform, `shape` the Shape's `{ kind, width, height, depth, radius }` or null, `body` the Body type or null (v1.1: a marker need not repeat its actor's size) |
166
+ | `hub.placeAt(playerId, at, facingDeg?)` | move a player's body; reaches the client as a clamp |
167
+ | `hub.hold(playerId, at?, facingDeg?)` / `hub.release(playerId)` | hold a player still (§8) |
168
+ | `hub.setHud(spec, playerId?)` | the declared HUD, for everyone or one player (§9) |
169
+ | `hub.hide(actorId)` / `hub.show(actorId)` | server-declared actor visibility (§10) |
170
+ | `hub.move(actorId, { x, y, z, rotationY }, { overMs }?)` | move a kinematic scene actor, at once or in a straight line over `overMs`; any subset of the fields (§10, v1.1) |
171
+ | `hub.tint(actorId, color)` | paint a Shape actor `#rrggbb` for everyone; `null` puts back its authored colour (§10, v1.1) |
172
+ | `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) |
173
+ | `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) |
174
+ | `hub.spawn(fromActorId, { x, y, z, rotationY }?)` / `hub.despawn(id)` | a copy of a scene actor for everyone, returning its id (§10, v1.2) |
175
+ | `hub.tune(playerId, { speed, jump })` | one player's own walk controller, as multipliers of the preset (§6, v1.2); `null` puts the preset back |
176
+ | `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) |
177
+ | `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) |
178
+ | `hub.seat(playerId)` | v1.6: the seat actor id a player sits on, or null (§6) |
179
+ | `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) |
180
+ | `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) |
181
+ | `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) |
182
+ | `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 |
183
+ | `hub.npc(actorId)`, `hub.npcs()` | the place's NPC bodies (§13) |
184
+ | `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) |
185
+ | `hub.result(playerId, result)` | the player's result for this visit (§7) |
186
+ | `hub.end(playerIds?)` | the game is over for these players (default: everyone): they go back through the door |
187
+ | `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 |
188
+ | `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 |
189
+ | `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 |
190
+ | `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 |
191
+ | `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 |
192
+ | `hub.send(playerId, data)`, `hub.broadcast(data)` | the game's own messages |
193
+
194
+ `hub.go` is how any place launches: in dev it mints `hub.<place>.<random>` and
195
+ tells each client to join that named session. Where the host has hub ops
196
+ (`session.hub`, a session ghost pinned to a hub place) it fires the door's pad
197
+ (`hubPadUpdate`, with the group `hub.pad` gathered): ghost fixes the group and
198
+ the instance, a late join included by the door's own `lateJoin`, and each member
199
+ is told to go through (`hub-go` with `pad` and no `key`). `instance` is ignored
200
+ there; the return value is the pad's id. Doors in dev are `HubDoor` scene actors
201
+ (`{ id, to, … }`, `to` a place id, or `deck:<name>` for a deck the town's
202
+ `castle.json` `devDecks` names, with the door's own `title`, `minPlayers`,
203
+ `maxPlayers` and `lateJoin`; other props are the place's own, such as where
204
+ returning players come out); the door table replaces them without a deck
205
+ change. A door faces its local +z, so it may stand in any wall: the trip
206
+ swings its leaf about its left edge (as you face it) and films through it along
207
+ its own rotationY. On the dev serve a `deck:<name>` door reads those four from the
208
+ destination's own `castle.json` (the serve hands the server each `devDecks`
209
+ deck's castle.json as `import.meta.env.CASTLE_DEV_DECKS`), and the check
210
+ refuses a door whose props disagree with it, so the published town cannot
211
+ drift from what dev played (v1.1). A place keeps its own record of the instances it launched until ghost
212
+ presence can say who is inside.
213
+
214
+ **Cabinets (v1.7).** A door may lead to a classic Castle deck (a Scene Creator
215
+ deck, which is not a hub game and is not changed): an arcade cabinet. The host
216
+ plays the deck itself, over the place, under the hub's cover and with the hub's
217
+ Back; nothing is reported and nothing is granted. Web hosts only.
218
+
219
+ - A cabinet is a `HubDoor` actor whose board from ghost carries `classic`
220
+ (`hub.board(door.id).classic`: `{ deckId, title, label, daily, better, cover,
221
+ top: [{ username, score, photo, frame }] }`, `score` already words, the
222
+ pictures data URIs or null). `hub.doors()` says `classic: true` for it, false
223
+ until the board is read, and the door takes its title from the board like
224
+ any door to another deck; a classic deck its creator never titled reads as
225
+ Castle's placeholder (`deck-` and four characters), which is no title, so
226
+ the door keeps its own (`HubDoor.title`), on its card too. A place marks the actor `"kind": "cabinet"` in its
227
+ `HubDoor` (with any `to` of the `deck:<name>` form, such as `deck:classic`):
228
+ such a door does not swing (the trip's camera goes up to it instead), is not
229
+ in the Doors list (§5), and has no pad with ghost, so `hub.pad` on it tells
230
+ ghost nothing.
231
+ - `hub.go(doorId, [playerId])` on a classic door fires no pad (ghost would
232
+ refuse: it is not a pad door) and places no session. Each player named is
233
+ told to go, each alone (`hub-go` with `classic: true`, §12); where the host
234
+ runs the hub only signed-in players go. It returns the door id, or null when
235
+ nobody went. A door that stayed shut for a player is not tried again until
236
+ they step off its pad, as for any door (`hub.pad` still says who stands
237
+ there).
238
+ - The trip (the client, §5): the door-open beat and the cover, then the player
239
+ leaves the place's session and waits under the cover until Back.
240
+ - The card. The kit's server sends a cabinet's card -- title, label, cover,
241
+ and up to five rows of photo, frame, username and score -- to each player
242
+ who comes within 14 m of it, once per version of the card, and the hub
243
+ chrome draws the card of the cabinet a player stands nearest (within 5 m)
244
+ over it, small: a chip with the best score and that player's photo in a
245
+ circle, the frame over it, a little larger. A tap on the chip opens the
246
+ whole board (cover, title, label, every row) and a tap on the board, or
247
+ walking away, closes it; a cabinet with no score draws no chip. A place
248
+ draws none of it and ships no client code for it. The size rules are in §12.
249
+ - On the dev serve there is no ghost, so no board: a cabinet is inert, and a
250
+ place says so on its label. `{ k: 'hub-dev-classic' }` (§12), honoured only
251
+ by a dev session, gives every cabinet door a stand-in board so the card and
252
+ the trip can be exercised; its trip is told `dev` and asks no host.
253
+
254
+ **Layer doors (v1.11).** A door may lead to a place ghost puts on public
255
+ layers, as it does a town, rather than in an instance per pad: a village, a
256
+ district, another town (the door row's placement is `layer`). A place marks
257
+ the actor `"kind": "layer"` in its `HubDoor`. Ghost holds no pad for such a
258
+ door, so `hub.pad` on it tells ghost nothing, and `hub.go(doorId, playerIds)`
259
+ fires none: each signed-in player named is told to go (`hub-go` with no `key`
260
+ and no `pad`), their client asks the host (`Hub.go`), and ghost steers them to
261
+ a layer of the destination with their party and friends. It returns the door
262
+ id, or null when nobody went. Only a public layer of a deck's main place has
263
+ that place's minds (§13), so a place whose NPCs have minds is reached by a
264
+ layer door. On the dev serve the door is a `deck:<name>` door like any other.
265
+
266
+ ## 5. Arrival and exit
267
+
268
+ - Players sent together by one `hub.go` arrive together: the kit holds a group's
269
+ first arrival still, up to 1.5 s, for the rest, places them in a row at
270
+ `arrival.actor` spaced by `arrival.spread`, and calls `arrive` once with all
271
+ of them. Their way back says the same group size (the hello's `party`, kept
272
+ on the return ticket), so they come back out together; one who stayed
273
+ behind costs the rest at most that 1.5 s.
274
+ - **Arrival facing is contract data**, not scene metadata (M0 gap 9): the body
275
+ faces `arrival.face`, and the client's camera starts behind it.
276
+ - A late joiner arrives the same way, alone.
277
+ - **Jumping to a door.** In a town (a place with no `result`) the chrome's Doors
278
+ button lists the place's doors; Go puts the player on that door's pad (the
279
+ `HubPad` actor naming it, v1.10: inside its radius, so the pad counts them;
280
+ v1.20: on a spot no one stands within 1.1 m of, a ring 1.2 m about its
281
+ middle first, then nearer its edge, then the middle, else the spot with the
282
+ most room), facing the door, or 7 m in front of a door with no pad, in the
283
+ door's own frame (at most once a second; never a held player). It is a walk, not a trip: the player stays in this session. A game
284
+ has no list.
285
+ - **Where a player came from** is ghost's arrival where the host has hub ops
286
+ (the door row the player was placed by, `fromDeckId` and `doorId`); the
287
+ client's hello names it only in dev.
288
+ - **A production trip** (a `hub-go` with `pad` and no `key`) is the host's: the
289
+ client asks `Hub.go(door)`, loads the content pack the handoff names under the
290
+ cover (`bundleHash`, `contentUrl`; content-pack.md) and joins with
291
+ `Multiplayer.join({ mode: "hub", handoff })`. A refusal, a handoff without a
292
+ pack, or a pack that fails keeps the door shut and gives the acquisition back
293
+ (`Hub.cancel`). The way back is `Hub.back()`; the host's own Back control is
294
+ answered the same way (`Hub.onBack`), and while the host's trail holds a hub
295
+ trip the kit does not draw its own Back, since the host draws one. Nothing of
296
+ the destination is mounted until the host commits the join
297
+ (`multiplayer.joinState()`); a join it does not commit leaves the player's
298
+ place as it was: a door's trip rejoins the session it left when that is not
299
+ itself a spent hub join, else leaves by that place's way back, and a way back
300
+ is tried once more. A join the host committed whose session then closes
301
+ before placing the player (a full layer refusing the socket after its
302
+ hello; `joinState()` `'lost'`) is not waited out: at the root of the host's
303
+ trail the runtime's first join is made again into the place already loading,
304
+ anywhere deeper the player leaves by that place's way back, twice at most.
305
+ Acquisitions and `Hub.cancel` run one at a time.
306
+ - **A place replaced under its players (v1.18).** When a place's session ends
307
+ under a player who is not on a trip (a new version of it was saved, or its
308
+ server stopped): a game is left as before ("The game ended", then its way
309
+ back); any other place reached through a door (the host's trail holds the
310
+ trip) is left by its way back at once, with a line saying it was updated
311
+ ("This place was updated. Back to <the place left>…"), and is entered again
312
+ through its door, which acquires the new version and its content. A join
313
+ cannot be made again from inside such a place: its handoff is spent, and
314
+ only a door's acquisition names the release to mount. The way back is asked
315
+ once per ending; one that is refused leaves the player where they are with
316
+ the host's Back control, as any refused way back does. The town itself, at
317
+ the root of the host's trail, joins again where it stands with the join the
318
+ runtime began with ("Reconnecting…"; the kit did this before v1.18, and it
319
+ is written down here). A player barred from the hub is neither sent back nor
320
+ joined again. The place's server sees nothing new: the players of the old
321
+ session had `leave`, and those who walk back in `arrive` like anyone.
322
+ - **A cabinet's trip (v1.7).** A `hub-go` with `classic` is a hub trip with no
323
+ destination session and no content. The client asks `Hub.go(door)`, which a
324
+ host that can play classic decks answers `{ status: 'ok', kind: 'classic' }`
325
+ once it has committed the trip itself (there is no session to join). The
326
+ trip plays the door-open beat (the camera goes up to the cabinet) and
327
+ covers; on that answer the client leaves the place's session -- the place is
328
+ left, not held -- and waits under its cover, away: no scene swap, no content
329
+ pack, the place's scene as it was. It pushes the same way back a door's trip
330
+ pushes, so Back (the host's control, `Hub.onBack`) is the ordinary
331
+ `Hub.back()` return: a hub join on the handoff into the place, arriving at
332
+ the cabinet's door. While away nothing else runs: no friends asked, no
333
+ trips, no talk, no idle play. Anything but that answer keeps the door shut
334
+ as for any door: a refusal or `unavailable`, a host with no doors, and a
335
+ host from before cabinets, whose ordinary handoff is given back
336
+ (`Hub.cancel`). The cover waits up to 40 s for the host (its own limit on
337
+ `Hub.go` is 30 s); should the host answer after that, the client follows it
338
+ and goes away then. A way back that cannot be made (refused, or not
339
+ committed after one more try) leaves the player away, to press Back again,
340
+ since the host is still showing the deck.
341
+ - **Finding a friend (v1.9).** In a town (a place that declares no `result`)
342
+ the chrome's People button lists everyone here, the player's friends first.
343
+ A friend is someone the host's `Hub.friends` names (so only a production hub
344
+ place has any; on a page served from localhost `?hubFriends=all` makes
345
+ everyone one). Every row has where that player is under their name; a
346
+ friend's has Join, anyone else's Find, and anyone standing on a door's pad
347
+ or beside a door has Go there (a jump to that door's pad, as Doors > Go). Where is the place server's word (`hub-where`, §12): "on the
348
+ <door> pad" for a `HubPad` actor's circle, "near <door>" within 7 m of a
349
+ door, else the place's `where` hook (§4), else "in town". Join
350
+ (`hub-goto`) puts the player beside that friend, facing them, as a jump to a
351
+ door does, but never on a door's pad nor at its edge, theirs included (v1.19:
352
+ beside a friend on a pad is just off its edge, so joining their game is a
353
+ step the player takes): a town only, at most once a second, never a held player, never
354
+ across a block; a sitter stands first. The server does not know who is whose
355
+ friend, so it moves a player beside any player of the session they may see;
356
+ only the chrome's list limits Join to friends. Find moves nobody: it puts
357
+ the pointer on that player (Stop takes it off), so anyone can be walked to
358
+ by name. A friend, or a found player, more than 12 m off (past where names
359
+ are drawn) gets a small pointer: a chip over them with
360
+ their name and distance, or at the screen's edge with an arrow when they are
361
+ out of view, three at most. A friend the host names who is not in this
362
+ session is listed too: "in another part of town" (another layer; Join is the
363
+ jump below), or, on a host that says which door's game they are in
364
+ (`door` on a `Hub.friends` row), "inside <door>" (Join is a jump to that
365
+ door). A game lists only who may be reported, as before.
366
+ - **Starting next to a friend (v1.12).** A player who walks into a town (no
367
+ door, no jump) and finds a party member or a friend in the same layer is put
368
+ beside them, once: the client asks the place (`hub-goto`) for a party member
369
+ first, else the first friend here in the host's order, as soon as the host
370
+ has named its friends, within 12 s of arriving and only while the player is
371
+ still within 4 m of where they came in; the toast says whom ("You're next to
372
+ amy"). Which layer a player lands in is ghost's pick (the party's layer,
373
+ then a friend's, then the fullest with room), so a friend in a full layer is
374
+ not started beside; they are in the People list with Join. A friend inside a
375
+ game behind one of the town's doors (a host that names the door) is told of
376
+ in a toast, with Join in the People list. Nothing happens for a player with
377
+ no friend here, or on a host without `Hub.friends`.
378
+ - **Parties (v1.10).** In a town, players may go about as a party of up to
379
+ eight. Invite is on a player's row in the People list and on a small button
380
+ once the player has stood within 2.2 m of someone for 1.5 s (offered for 8 s, never over an open card or list); the invited player is asked ("ada
381
+ invited you to their party": Join party / No thanks; one invitation waits on
382
+ a player at a time, for 60 s) and on yes joins the inviter's party, leaving
383
+ any other. Party members are first in the People list, with Join (beside
384
+ them) and a pointer like a friend's, and the list has Leave party. In a
385
+ party, Doors > Go reads "Go together": the member who picks a door is put on
386
+ its pad and every other member here is asked ("ada: let's play Foot Race":
387
+ Go / Not now, for 45 s); each who says Go is put on the pad too, on a spot
388
+ of their own. Nothing else about a door changes: the pad counts who stands
389
+ on it and fires as it always did, and `hub.coming(door)` tells the place how
390
+ many answers are outstanding so it can hold the countdown (a party's
391
+ proposals count there for at most 20 s in any minute, and an answer names
392
+ the invitation or proposal it answers, so it cannot land on a later one). A party is the
393
+ place's own (ghost's parties and the host's `partyId` are not involved) and
394
+ lasts while its layer does: a signed-in member away through a door is kept
395
+ for 30 minutes and is in the party again on return, a guest only while
396
+ here, and a party down to one member ends. No invitation crosses a block,
397
+ and a member a block hides from another is not named to them. A player's
398
+ party messages are limited to a burst of six, then one a second. A game has
399
+ no parties.
400
+ - **Joining a friend in another layer** (where the host has `Hub.friends`, i.e.
401
+ a production hub place): a town asks the host every 20 s which of the
402
+ player's mutual friends are in it or in another layer of it; the ones
403
+ elsewhere are in the People list with Join. Join is `Hub.jump(userId)`: a production trip
404
+ as above to the same place in the friend's session, with no door, no return
405
+ ticket and no step on the host's trail, so the way back is unchanged. The
406
+ content is the place's held release when the handoff names it, else the pack
407
+ the handoff names. The player arrives at `arrival` like any arrival with no
408
+ door (`from` is null), not next to the friend. A jump the host refuses stays
409
+ put; one it does not commit rejoins the session it left when that can be
410
+ joined again, else leaves by the place's way back. A host that answers
411
+ `unavailable` or does not know the command is not asked again.
412
+ - **Falling (v1.1).** A scene can have no ground at all (`"ground": { "none":
413
+ true }` at the scene file's top level, which the engine and the server both
414
+ read): a pit, lava, islands in the sky. A place whose players can fall
415
+ declares `fallY` (or gets -20 in a scene with no ground): a player whose body
416
+ drops below it is handed to the game's `fall(hub, playerId)` hook, and if
417
+ they are still down there afterwards the kit puts them back at the arrival.
418
+ A held player is not caught (the game holds whom it has already dealt
419
+ with). The hub client stops its own player's fall a metre under `fallY`
420
+ (the snapshot's `hubPlace.fallY`), since the server reads no pose below the
421
+ world's floor (-30 m) and a report that skipped past it would never be
422
+ caught. `fallY` must sit below everywhere a player stands, or the arrival
423
+ itself counts as fallen.
424
+ - **Exit** is always through the door the player came in by: the hub-drawn Back
425
+ control, `hub.end`, `maxDurationSec`, a crash or a republish. The game cannot
426
+ name the destination; the client's return ticket does (ghost's, once it
427
+ exists). Returning players come out at that door, facing the square.
428
+
429
+ ## 6. Controller presets
430
+
431
+ | preset | what | status |
432
+ | --- | --- | --- |
433
+ | `walk` | physics-3d's `Player`: tank-style walk/turn, drag-stick on touch, jump, follow camera; client-predicted, server-clamped | v1 |
434
+ | `vehicle`, `fixed-camera` | reserved names | refused until built |
435
+
436
+ A game chooses a preset; it does not extend one (HUB.md open question 6 stays
437
+ open for v2). The scene's `Player` actor is the spawn and the preset's tuning
438
+ (`camDistance`, `camHeight`, speed props the behavior already has).
439
+
440
+ **Tuning one player (v1.2).** `hub.tune(playerId, { speed, jump })` changes
441
+ one player's own controller: their walk speed and jump, as multipliers of the
442
+ preset's (the scene Player's `speed` and `jumpSpeed`), for the +1 games where
443
+ a stat makes you faster. `speed` is clamped to 0.25-3 and `jump` to 0.5-2.5;
444
+ either may be left out (1); `null` (or both 1) puts the preset back. Only that
445
+ player's client is told (`hub-tune`), and the server's movement clamp for that
446
+ player follows the larger multiplier, so a tuned player is not pulled back
447
+ while everyone else keeps the place's limit. It needs multiplayer-3d from
448
+ 2026-10-03 or later, whose clamp reads a player's own limit; on an older one a
449
+ player tuned past twice the preset is pulled back. A tune lasts the visit and
450
+ goes with the player.
451
+
452
+ **Grabbing and throwing (v1.3).** A place with `grab` in its manifest lets
453
+ players pick up its loose objects -- scene actors whose `Body` is `"dynamic"`
454
+ -- and throw them. The hub draws a Grab button (bottom right; E or F on a
455
+ keyboard) whenever such an object is within about 1.6 m in front of the
456
+ player, and it holds it: `holdDistance` in front of the player (never so close
457
+ it touches them) and `holdHeight` above their feet, following them as they
458
+ walk and turn. The button becomes Throw, which lets go along the way the
459
+ player faces at `throwSpeed`, a quarter of that upward. One object at a time;
460
+ never a player (other players are not scene objects).
461
+
462
+ What can be grabbed is what multiplayer-3d already hands this client to
463
+ simulate: a loose object nearest this player within its reach. A held object
464
+ stays in reach, so the client stays its owner, and its poses are reported and
465
+ checked by the server exactly as any owned object's are: an owner's report
466
+ may move an object at most 40 m/s (multiplayer-3d `MAX_OBJECT_SPEED`), and a
467
+ report past that hands the object back to the server. `throwSpeed`'s top,
468
+ 14 m/s, sits well inside that, so no throw is cut short by it. Once a thrown
469
+ object leaves the thrower's reach the server simulates it; the kit lets it fly
470
+ for up to 3 s, or until it slows to 4 m/s, before the server's cap on how fast
471
+ a player's shove may send an object applies again. The flight is the server's
472
+ to bound: a thrown object in the server's hands never goes faster than the
473
+ place's `throwSpeed` (and a tenth more), whatever the thrower reported,
474
+ checked after every physics step (multiplayer-3d's per-object `speedCap`; with
475
+ an older multiplayer-3d a throw is held to a shove's 4 m/s once the server has
476
+ it).
477
+
478
+ The place hears every grab and throw (the `grab` hook, §4) and may refuse a
479
+ grab: the player lets go at once. The server also refuses one by itself when
480
+ the object is not a loose object of the place, is hidden, is not that
481
+ player's to simulate, or is more than 4 m from them, or when the player is
482
+ held (§8) or has not arrived; a player's grab and throw messages are limited to
483
+ 4 a second. A hold also ends when the place hides the object, when the
484
+ multiplayer kit hands it to someone else, when the player is held, on a trip
485
+ and at a game's end. `hub.drop(playerId?)` makes a player let go (a goal, a
486
+ whistle): the object falls where it is. A place without `grab` draws no button
487
+ and is sent exactly what it was.
488
+
489
+ **A steadier offer (v1.22).** The offer is tested afresh every frame: within
490
+ the reach, within 60 degrees of facing, and this client's to simulate (the
491
+ multiplayer kit hands an object to the nearest player). At any of those edges
492
+ -- a player turning, two players near one object -- the button comes and
493
+ goes, and on a phone a press lands on nothing. A place may set, in `grab`:
494
+
495
+ - `reach` (1.6-3 m): objects are offered this far from their near side instead
496
+ of 1.6 m.
497
+ - `steady: true`: once an object is offered, it stays the one offered while
498
+ its near side is within the reach and 0.4 m more and it is within 90
499
+ degrees of facing, even when another is nearer. When it fails that for a
500
+ moment -- briefly someone else's to simulate, a turn past the cone, a step
501
+ back -- the button stays up for 600 ms. A press in that time waits up to
502
+ 500 ms for the object to pass the test again (this client's own included)
503
+ and grabs it then; if it does not, the press is dropped. Another object
504
+ that passes the ordinary test takes the offer over meanwhile.
505
+
506
+ With either set, an object is also never offered when its centre is more than
507
+ 3 m from the player's, and less the faster the player is moving (their body's
508
+ speed, jumps included, or their tuned speed, over the 0.2 s the server's view of
509
+ them may trail), keeping inside the server's 4 m in ordinary play; a grab the
510
+ server still refuses is let go, as any refused grab is. Nothing changes on the server: it checks every grab
511
+ as it always has, and the client still sends a grab only for an object that
512
+ is its own at that moment. A place that sets neither runs the offer it always
513
+ did, and is sent and drawn exactly what it was.
514
+
515
+ A refusal and `hub.drop` bind the hub client, which is the only client a hub
516
+ place has; they do not take the object from its owner on the server. A
517
+ modified client can carry a loose object it owns whatever the place says,
518
+ exactly as it can push one in any multiplayer-3d deck today, so an object the
519
+ place must keep out of players' hands is made kinematic (moved by `hub.move`),
520
+ not merely refused.
521
+
522
+ **Idle play (v1.6).** A place with `idle` in its manifest gives players
523
+ something to do while they wait or hang out, still without client code: the
524
+ hub draws an emote picker, Sit and Stand, and the place's sounds. A place
525
+ without it draws nothing new and is sent exactly what it was.
526
+
527
+ - **Emotes** (`idle.emotes`). An emote button (☺, bottom right, above Grab)
528
+ opens the kit's emotes: `wave` 👋 (a side-to-side sway, 2 s), `dance` 💃
529
+ (bounce, sway and twist, 2.4 s), `cheer` 🎉 (three hops, 1.6 s), `bow` 🙇 (a
530
+ bow forward, 1.6 s) and `spin` 🌀 (a full turn, 1.2 s). Everyone sees it on
531
+ that player's avatar, with the emoji rising over their head. It is drawn
532
+ only: the avatar's model moves inside its drawn node, never its body, its
533
+ network pose or what anyone simulates. The server takes one emote per
534
+ player every 2 s, refuses an id the kit does not have and a player who has
535
+ not arrived, and asks the place's `emote` hook, which may refuse it.
536
+ `hub.emote(playerId, id)` plays one on a player from the place itself (an
537
+ NPC's greeting, a goal) and is neither rate-limited nor offered to the hook.
538
+ - **Seats** (`idle.seats`). A scene actor carrying `HubSeat` (`{ face,
539
+ height }`, both optional) is a seat. A seat stays where it was authored: one
540
+ with a `"dynamic"` or `"kinematic"` `Body` is refused by the check and
541
+ ignored by the hub. A player standing within about 1.5 m of
542
+ a free one is offered Sit (bottom centre). The server checks the seat is one,
543
+ shown and free (one player per seat), the player is here, not held by the
544
+ place and within 2.5 m, and asks the place's `sit` hook; then it holds them
545
+ on the seat (§8): over its centre, `height` metres above its Transform
546
+ (default: the top of its Shape plus a standing body's 0.85 m, so a sitter on
547
+ a solid seat rests on it), facing `face` degrees (default the seat's own
548
+ `rotationY`). Everyone draws a sitter lowered 0.45 m and tipped back a
549
+ little. Stand, any walk, turn or jump input (a tap on touch included), or a
550
+ jump to a door gets them up where they are. A seat is a hold: a held player cannot sit, and the
551
+ place's own `hub.hold` or `hub.release` of a sitter, a game's end, leaving,
552
+ or the place hiding the seat stands them. `hub.seat(playerId)` says where a
553
+ player sits. Sit and Stand are limited to 3 a second per player.
554
+ - **Sounds** (`idle.sounds`). `hub.sound(actorId, file, { loop, volume,
555
+ radius })` plays one of the files the place lists at a scene actor (or a
556
+ spawned copy) for everyone, its volume falling off in a straight line to
557
+ nothing `radius` metres away from the listening player. At most 4 loops at
558
+ once in a place (`hub.sound(actorId, null)` stops one; another sound at the
559
+ same actor, a one-shot included, replaces it) and 4 one-shots a second (a burst of 8). A player who
560
+ joins hears a loop from where everyone else is in it. Browsers start audio
561
+ only after a gesture: a loop waits for the player's first tap or key, and a
562
+ one-shot that cannot play then is dropped. The files are the deck's own:
563
+ bundled into its page where the deck runs as itself (a town), and carried in
564
+ its content pack's `audio` (`docs/content-pack.md`), so a game reached
565
+ through a door sounds too, on a town whose engine is this kit or later. A
566
+ town on an older engine ignores `audio` and the game is silent there. A
567
+ place plays only its own content's files, never a same-named file of the
568
+ town's.
569
+
570
+ **Quick reactions and phrases (v1.11).** In every hub place the chrome has a
571
+ speech button (💬, bottom right, above the emote button) that opens a row of
572
+ emoji (👍 😂 ❤️ 😮 👋 🎉) over the place's canned phrases: in a town "Over
573
+ here!", "Let's play…", "Wait for me", "Yes!", "Not now"; in a game "Over
574
+ here!", "Wait for me", "Yes!", "Not now", "Good game!", "Again?", "Back to
575
+ town?". A pick is `{ k: 'hub-say', r }` (a reaction, by index) or `{ k:
576
+ 'hub-say', p }` (a phrase, by id); the server carries no text, refuses
577
+ anything else, limits a player to a burst of three and then one every 1.5 s,
578
+ and tells everyone here a block does not hide the speaker from (`hub-said`).
579
+ "Let's play…" names the door the speaker stands within 12 m of ("Let's play
580
+ Tile Fall"), else "Let's play something". Each client words what was said
581
+ itself: a bubble over the speaker for 4 s (the emoji, or the line), and for a
582
+ phrase a line in a small feed above the dock for 9 s, three at most. "Over
583
+ here!" from a party member or a friend puts the pointer (§5) on them for
584
+ 10 s, and a "Let's play" that names a door is offered to everyone who heard it
585
+ as a question for 20 s ("bo: let's play Tile Fall": Go / Not now), Go being a
586
+ jump to that door's pad. This is for everyone, guests included; nothing a player types is
587
+ carried. No place opts in or out, and no hook hears it.
588
+
589
+ **Free-text chat (v1.12).** Two players may type to each other only when
590
+ they follow each other on Castle and both are over 13; a guest, or a player
591
+ whose age Castle does not know, has no chat. That rule is ghost's and ghost
592
+ enforces it; neither the kit nor a place's server is trusted with it or
593
+ carries a word of it. Where the host has the commands (`Hub.chat`, `Hub.say`,
594
+ `Hub.reportChat`; a web host from 2026-10-03), the kit asks the host every
595
+ 2.5 s (every 15 s while nobody here can be chatted with) what this player may
596
+ read and whom their words would reach, and the speech card gains a line and a
597
+ field: "Chat reaches bo, amy" over a Message field, or "Follow each other to
598
+ chat" and no field, which is all a player is ever told about why (never
599
+ another player's age). A sent line goes through the host to ghost, which
600
+ filters it as classic party chat is filtered and hands it only to the players
601
+ here who pass the rule with the sender, so in a group each player reads only
602
+ the lines of the players they follow who follow them back. A line is drawn
603
+ like a phrase: over its speaker for 6 s and in the feed; a tap on another
604
+ player's line in the feed offers Report (`Hub.reportChat`). What was said
605
+ before a player arrived is not shown to them. On a host or SDK without the
606
+ commands nothing is drawn and nothing is asked. A deck changes nothing.
607
+
608
+ **Player contact is not in v1.** Other players are kinematic capsules on every
609
+ client, so nobody can be shoved (M0 gap 4). That is an engine rule, not a
610
+ contract field; a game that needs it waits for it.
611
+
612
+ ## 7. Results
613
+
614
+ ```js
615
+ hub.result(playerId, { outcome: 'win', score: 16900, stats: { laps: 3 } });
616
+ ```
617
+
618
+ - Server only, at most once per player per visit; a second call is refused and
619
+ logged.
620
+ - **The outcome may be left out (v1.1)** where the score says it all: a solo
621
+ time trial's time, a co-op run's time. Such a result carries a `score` (a
622
+ result with neither is refused); the town words it as the title and the
623
+ score (`"Summit Sprint: 42.1 s"`), ghost records it without touching the
624
+ win streak, and the board ranks it like any other.
625
+ - Validated against `result`: `outcome`, when given, must be one of `outcomes`; `score` a
626
+ finite number inside `[min, max]` when `score` is declared, absent otherwise;
627
+ `stats` only declared keys, numbers finite, strings ≤ 40 chars. No free text:
628
+ the town writes every word the player sees (`"Foot Race: win · 16.9 s"`), from
629
+ `title`, `outcome` and `score.unit`.
630
+ - `score.unit`: `"ms"`, `"s"` or `"points"`; `better`: `"higher"` or `"lower"`.
631
+ - Where it goes: to the host's `hubResult` op where the host has hub ops
632
+ (`session.hub.reportResult`: validated again against the shape published with
633
+ the server bundle, one per player per visit, rate-limited, recorded by ghost
634
+ for a signed-in player behind a curated door), and to the player's own client
635
+ for display.
636
+ - What a town sees: where the host has hub ops, the kit reads ghost's record of
637
+ each arriving player (`hubResultsRead`) and hands the newest result from the
638
+ deck they came from to `arrive` as `carry.result` (`verified: true`), and sends
639
+ it to that player's client for the ribbon. The client's own carried copy is
640
+ read only in dev, as unverified display; nothing of value may be granted from
641
+ it.
642
+ - A player who leaves without one has no result for that visit.
643
+ - **Reading a player's results (v1.5).** `hub.results(playerId)` hands deck
644
+ code what ghost holds of a signed-in player: `recent`, their newest results
645
+ in any hub place (`{ deckId, place, title, outcome, score, unit, better,
646
+ stats, at }`), and `records`, one per place they have played (`{ deckId,
647
+ place, title, plays, outcomes: { win, lose, draw }, bestScore, unit, better,
648
+ winStreak, lastOutcome, lastScore, lastAt }`), each list at most 20, with
649
+ `readAt`. The kit reads it with the arrival read and again once a minute for
650
+ everyone here (one read for up to 24 players), so a place never calls the
651
+ host's results read itself. A copy: changing it changes nothing. Null on the
652
+ dev serve, for an anonymous player, and until the first read lands.
653
+
654
+ ## 8. Holding a player still
655
+
656
+ `hub.hold(playerId, at?, facingDeg?)` pins a body at `at` (default: where it
657
+ is) until `hub.release`. The kit re-clamps every tick the client drifts, and the
658
+ held list rides in the delta so the hub client stops reading input instead of
659
+ fighting the clamp (M0 gap 3: a clamp was sent only when the pose changed). A
660
+ race's countdown line: `hold` on arrival, `release` at "go". A seat (v1.6, §6)
661
+ is a hold too: the place's `hold` replaces it and its `release` ends it, which
662
+ stands the sitter.
663
+
664
+ ## 9. The HUD vocabulary
665
+
666
+ The only way a Tier 0 game puts words on screen (M0 gap 1). Drawn by the hub
667
+ chrome, never the game:
668
+
669
+ ```js
670
+ hub.setHud({ title: 'Foot Race', big: '3', text: 'get ready', timer: { since: hub.now } });
671
+ hub.setHud(null); // nothing
672
+ hub.setHud({ text: 'you are it!' }, playerId); // one player's override; null clears it
673
+ ```
674
+
675
+ | field | rule |
676
+ | --- | --- |
677
+ | `title` | ≤ 40 chars, small caps across the top |
678
+ | `big` | ≤ 12 chars, the large line (a countdown digit, "FINISH") |
679
+ | `text` | ≤ 120 chars, one line under it |
680
+ | `timer` | `{ since: simMs }` counts up, `{ until: simMs }` counts down; shown in `big` when `big` is absent |
681
+
682
+ Longer strings are cut, other keys dropped. A per-player spec replaces the
683
+ shared one for that player.
684
+
685
+ ## 10. Actor visibility
686
+
687
+ `hub.hide(actorId)` removes a scene actor for everyone: its server body is
688
+ disabled now, and every client (including later joiners) removes it.
689
+ `hub.show(actorId)` puts it back as authored. Only actors of the place's scene
690
+ (M0 gap 2: the race's start gate). On the client a hidden actor is moved far
691
+ below the ground with its collider rather than despawned, so it is meant for
692
+ actors that do not move by physics.
693
+
694
+ `hub.label` puts words over a scene actor, drawn by the hub chrome like the
695
+ HUD: a pad's "3 of 6", an NPC's line, the hill's king.
696
+
697
+ **Goals (v1.13).** `hub.label(actorId, text, { style: "goal", to: [playerIds] })`
698
+ is where the place is sending those players: an errand's person, the counter
699
+ to fetch from. The hub chrome draws it as a pointer rather than a label: over
700
+ the actor while it is on screen, else at the screen's edge with an arrow along
701
+ the way to it, with the distance in metres beyond 6 m (the follow camera looks
702
+ down, so a far sign is rarely in view). A goal is one player's own: with no
703
+ `to` it is a `"sign"`. The two nearest are drawn; `null` clears one like any
704
+ label. A town on an engine from before v1.13 draws it as a tag.
705
+
706
+ **Labels in a town.** In a place with no `result` (a town, not a game) the
707
+ client draws a label only when its actor is near the player: the nearest
708
+ plain or `"tag"` label within 4 m and the nearest `"speech"` line within 9 m,
709
+ fading in and out, one of each at a time. A `"sign"` label (a street's or a
710
+ building's name, for finding the way, or a word the player must read from
711
+ where they stand, like the kit's own "Door shut" over a door) is drawn at any
712
+ distance. Other players' names show within
713
+ 12 m, smaller than in a game. A town labels everything it has -- every
714
+ statue, board, pad and NPC -- and all of it at once was a wall of text from
715
+ the arrival spot; the words are there when the player walks over. A game
716
+ place draws every label it sets, as before.
717
+
718
+ **Moving an actor (v1.1).** `hub.move(actorId, to, { overMs })` moves a scene
719
+ actor whose `Body` is `"kinematic"`: a moving platform, a sweeper, a gate that
720
+ slides open. `to` is any of `x`, `y`, `z` (metres) and `rotationY` (degrees);
721
+ the fields it leaves out stay where they are. With `overMs` (up to 60000) the
722
+ kit moves it in a straight line, a step each tick, from wherever it is now; a
723
+ later move replaces one under way. The kit drives the server body through its
724
+ kinematic target, so it pushes what it meets the way a door does, and every
725
+ client draws it from the pose the multiplayer kit already sends for kinematic
726
+ bodies. A game that wants a loop or a curve calls `move` again when the last
727
+ one ends (or every step, with no `overMs`). Refused, and logged once: an actor
728
+ that is not a kinematic actor of the place's scene, a number that is not
729
+ finite, a point outside the world box (|x|, |z| ≤ 200, -30 ≤ y ≤ 80), more
730
+ than 64 actors moving at once, and a `rotationY` beyond ±36000 degrees. A
731
+ finished move keeps its turn within one turn, so a sweeper that spins by
732
+ asking for `rotationY + 360` each time never grows. A hidden actor can be
733
+ moved; it stays hidden (the hub client applies visibility after the
734
+ multiplayer kit has written that frame's poses).
735
+
736
+ **Reading and putting back a loose object (v1.3).** A scene actor with a
737
+ dynamic `Body` is a loose object: multiplayer-3d hands it to the client
738
+ nearest it, which simulates it and reports where it is. `hub.pose(actorId)`
739
+ says where any body is as the server has it -- `{ x, y, z, rotationY,
740
+ velocity: { x, y, z }, owner }`, `rotationY` its heading (where its front
741
+ points, on the ground; an upright body's Transform.rotationY), `owner` that
742
+ client's player or null -- and null for an actor without one. `hub.reset(actorId, at)` puts a loose object
743
+ back where the scene authored it (or at `at`, any of `x`, `y`, `z`,
744
+ `rotationY`), at rest. If a client is simulating it, the server takes it back
745
+ first with the multiplayer kit's own handover, so that client stops moving its
746
+ copy and a late report from it is dropped; everyone then sees it where it was
747
+ put, and for half a second nobody may be handed it, so no client starts
748
+ simulating it from where it was. A ball back on the spot after a goal; props that fell off the pitch.
749
+ Refused, and logged once: an actor that is not dynamic (move a kinematic one
750
+ with `hub.move`), a point outside the world box, and more than 20 resets a
751
+ second (bursts of 40). An actor with the engine's `Ball` component is never
752
+ slowed to a shove's speed by the server; give it to an object meant to be
753
+ kicked hard, not to one only walked into.
754
+
755
+ **Spawning a copy (v1.2).** `hub.spawn(fromActorId, at)` copies one of the
756
+ place's scene actors (the template) for everyone, later joiners included, at
757
+ `at` (any of `x`, `y`, `z`, `rotationY`; the rest are the template's), and
758
+ returns the copy's id (`<fromActorId>~<n>`, never reused), or null.
759
+ `hub.despawn(id)` removes a copy. A copy is an actor like any other: move it
760
+ (when its template is kinematic), tint, hide and label it. It is the
761
+ template's components as authored, so a template can be a hidden prototype:
762
+ author one lantern, hide it at `ready`, and place copies where they are
763
+ needed. A copy's marker components come with it, but `actorsWith` lists only
764
+ the scene's own actors. A template has a `Shape` (a `Model` may ride on it);
765
+ not a template: a copy, an actor with a dynamic `Body` or a `Pickup`, a
766
+ `Player`, a `HubDoor`, `HubPad` or `HubNpc`. A copy a behavior removes on one
767
+ client is reported gone like any scene actor and is never re-made there; one
768
+ the place despawns is forgotten by every client, pose history included. Bounded: 96 copies
769
+ alive at once and 10 spawns a second with bursts of 40; past either, `spawn`
770
+ returns null and logs once, and a game tries again later. A copy a client
771
+ reports gone (the multiplayer kit's pickup rule) is gone for the game too.
772
+
773
+ **Recolouring an actor (v1.1).** `hub.tint(actorId, '#rrggbb')` paints a scene
774
+ actor drawn by a `Shape` for everyone, later joiners included; a Shape that
775
+ glows (`emissive`) glows in the new colour. `hub.tint(actorId, null)` puts its
776
+ authored colour back. A held plate turning green, a tile about to fall glowing
777
+ orange. Each client rebuilds a painted mesh, so the place has a budget: 20
778
+ changes a second with bursts of 40 (a change past it waits a tick or so, the
779
+ newest colour winning; repeating the colour an actor already has costs
780
+ nothing), and at most 128 actors painted at once. An actor drawn by a `Model`
781
+ cannot be painted (every client would rebuild the model), nor one with a
782
+ dynamic `Body` (a client rebuilds a body whose Shape changes, stopping it
783
+ dead). A textured face takes the colour as its tint.
784
+
785
+ ## 11. The platform avatar seam
786
+
787
+ A hub game never draws a player. The kit draws everyone, the local player
788
+ included, as their **avatar**: an id from the kit's set
789
+ (`imports/castle.hub-game/blueprints/avatar-<id>.scene`, v1: `0`-`3`). The
790
+ client says which in its hello; the server broadcasts every player's choice; a
791
+ change says hello again and respawns that player's body (M0 gap 8). Games never
792
+ see any of it.
793
+
794
+ Where the choice comes from is one function, `Avatar.current()` in the kit's
795
+ client:
796
+
797
+ - **The platform avatar**, one per account, the same in every place (HUB.md
798
+ decision 4). Ghost keeps it (`cauldron_hub_avatars`); the host serves it to
799
+ the kit through the SDK's `Avatar.get()` / `Avatar.set()`, which the hub
800
+ chrome's picker calls. Only a curated hub place (an enabled door leads into
801
+ or out of it) may change it; the host names the place, and anywhere else a
802
+ pick stays the runtime's own. A player who never chose wears a default fixed
803
+ by their user id. Anonymous accounts may choose: a template index carries no
804
+ text to moderate and nothing of value, and an anonymous account keeps its
805
+ user id when it signs up.
806
+ - **A stand-in pick** kept in `scene.persistent`, where there is no platform
807
+ avatar: a signed-out visitor, a host or SDK from before avatars, a deck that
808
+ is not a curated place (the dev serve). It lasts for the runtime, across
809
+ doors.
810
+
811
+ The hello never waits for the avatar: it goes out with what the kit has, and
812
+ says hello again when that changes. Picks are written one at a time; one ghost
813
+ refuses is undone.
814
+
815
+ Ghost also returns every listed player's platform avatar in the host's
816
+ `hubResultsRead` (`players[userId].avatar`), so a place's server can draw
817
+ players as ghost says rather than as their clients claim. Where the host has
818
+ hub ops (`session.hub`) the kit reads it for each player who says hello, and it
819
+ replaces the hello's choice unless a later hello changes it. Elsewhere (the dev
820
+ serve) the server takes each client's hello, which can only change how that
821
+ player looks.
822
+
823
+ **Avatar sets.** The kit has more than one drawing of the four avatars:
824
+ `toon` (the default, `blueprints/avatar-<id>.scene`) and `blocky`, `bean` and
825
+ `pixel` (`blueprints/<style>/avatar-<id>.scene`, models in `models/<style>/`,
826
+ art in `drawings/<style>/`). Which set is drawn is the **viewer's** own:
827
+ `Avatar.style()` in the kit's client reads the platform experiment
828
+ `hub_avatar_style` through the SDK (`experiment`, where the SDK has it; the kit
829
+ calls `experimentsReady` once before the first read and draws toon until the
830
+ host answers), and a viewer in a set sees every player in it, themselves
831
+ included, by the same avatar id. Anything else, an SDK without experiments or
832
+ a set the engine's files do not have, is toon, so nothing changes until an
833
+ experiment assigns a set. On a page served from `localhost` or `127.0.0.1`,
834
+ `?hubStyle=<style>` overrides it. Nothing about the set is on the wire and the
835
+ avatar id means what it did, so this is not a contract change: a game never
836
+ sees it, and the town's engine lays every set over a game's content pack as it
837
+ does toon's. Each model is at most 1,500 triangles and 8 draw calls, with no
838
+ outline pass, and its height is in `avatar.js` for what is worn over it. A
839
+ model in a set names its art through the import
840
+ (`imports/castle.hub-game/drawings/<style>/...`), because the engine looks an
841
+ art ref up as written in the deck's files.
842
+
843
+ **Marking a player (v1.1).** A game cannot touch an avatar, but it can mark
844
+ the player wearing it: `hub.mark(playerId, { text: 'RED', color: '#d1453b' })`
845
+ puts a tag in that colour over the player's avatar, above their name, for
846
+ everyone in the place (the player included, over their own body). `text` is
847
+ up to 16 characters, cut beyond; none draws a dot. `color` is `#rrggbb`, and
848
+ the hub chrome picks black or white words to read on it. One mark per player:
849
+ a second call replaces it, `hub.mark(playerId, null)` clears it, and a player
850
+ who leaves takes theirs with them. Refused, and logged once: a player who is
851
+ not here, or a colour that is not `#rrggbb`. A team colour for Zone Wars, a
852
+ red IT for Tag.
853
+
854
+ **Wearing a game's result (v1.4).** A mark lasts the visit; a **wearable**
855
+ goes with the player. `hub.wear(playerId, { kind: 'aura', color: '#9b5cff',
856
+ rarity: 6 })` puts one on the player's avatar: the kit draws it over the avatar
857
+ for everyone here (the player included, over their own body), and where the
858
+ host runs the hub it goes to ghost, which keeps one per account and hands it
859
+ back to every hub place on the arrival read (`players[userId].wearable` of
860
+ `hubResultsRead`), so the player wears it in the town and in every other game.
861
+ The latest call wins; `hub.wear(playerId, null)` takes it off everywhere.
862
+
863
+ - `kind` is a lowercase id (`/^[a-z][a-z0-9-]{0,23}$/`). The kit draws
864
+ `"halo"` (a thin glowing disc over the head), `"aura"` (a glowing disc at the
865
+ feet) and `"orbit"` (small sparks circling the head, one more for every three
866
+ rarity); a kind it does not know is kept but not drawn, so a later kit may
867
+ draw more. `color` is `#rrggbb`; `rarity` an integer 0-9, which grows the
868
+ pieces and their glow a little.
869
+ - Ghost takes a wearable only from a curated hub place (an enabled door leads
870
+ into or out of it, the avatar's rule), only for a signed-in player, and at
871
+ most 30 changes a minute per player; the host checks the shape first.
872
+ Refusals are logged once and change nothing in this place: a guest's
873
+ wearable, and any on the dev serve, lasts the session.
874
+ - A wearable the game puts on wins over an arrival read that began before it,
875
+ as a new avatar choice does. A player who leaves takes theirs with them
876
+ (from this place; ghost keeps it).
877
+ - Refused, and logged once: a player who is not here, or a wearable that is
878
+ not exactly `{ kind, color, rarity }` in range. Nothing reaches ghost.
879
+
880
+ A prize from a roll, a crown for the day's champion: the reason a game is
881
+ worth playing elsewhere.
882
+
883
+ ## 12. Wire (kit-internal, listed so a host or bot can speak it)
884
+
885
+ Client → server: `{ k: 'hub-hello', avatar, from, party, carry }` once per session join
886
+ (and again with `again: true` when only the avatar changed, v1.7);
887
+ `{ k: 'hub-dev-classic', on? }` (v1.7; the dev serve's stand-in for classic boards, §4, ignored by any session that is not a dev one);
888
+ `{ k: 'hub-door-jump', door }` (a town's Doors list, §5);
889
+ `{ k: 'hub-say', r }` or `{ k: 'hub-say', p }` (v1.11, §6);
890
+ `{ 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));
891
+ `{ 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);
892
+ `{ k: 'hub-grab', actor, op }` (v1.3, `op` `"grab"` or `"throw"`, §6);
893
+ `{ k: 'hub-emote', id }`, `{ k: 'hub-sit', seat }`, `{ k: 'hub-stand' }` (v1.6, §6);
894
+ `{ k: 'hub-npc-open', npc }`, `{ k: 'hub-npc-say', npc, text }` (authored mode
895
+ only), `{ k: 'hub-npc-end', npc }` (§13).
896
+ Server → client, in deltas and the WORLD snapshot: `hubPlace` (the place's
897
+ public manifest, with the `fallY` the session catches at, and `grab` (v1.3) only where the place sets it), `hubAv`, `hud`, `hidden`, `held`, `labels`, `tints` (v1.1,
898
+ actor id → `#rrggbb`), `marks` (v1.1, player id → `{ text, color }`), `hubDoors` (a town's `[{ id, title }]`, each with `featured: true`, `solo: true` or `need: n` where they apply (v1.14),
899
+ §5), `spawned` (v1.2, copy id → `{ from, x, y, z, rotationY }`) with
900
+ `spawnTemplates` (each template in use → its authored components), `hubWear`
901
+ (v1.4, player id → `{ kind, color, rarity }`; only once someone in the place
902
+ has worn one, and like `hubAv` without the players in a hidden pair), and in a
903
+ place with `idle` (v1.6) only the parts it turns on: `hubEmotes` (player id →
904
+ `{ id, at, until }`, simulation ms), `hubSeated` (player id → seat actor id),
905
+ `hubSounds` (actor id → `{ file, volume, radius, since }`, the loops playing).
906
+ Server → every client: `{ k: 'hub-sound', actor, file, volume, radius }` (v1.6,
907
+ a one-shot); `{ k: 'hub-went', players, door }` (v1.15, a town: to each player staying, who of the players they may see went through `door`); `{ k: 'hub-said', player, r }` or `{ k: 'hub-said', player, p, door? }` (v1.11, §6: to each client a block does not hide the speaker from). Server → one
908
+ client: `{ k: 'hub-go', door, key, place, scene, title, party }` (in production `key` is null and `pad` names the fired pad; a cabinet's, v1.7, has `classic: true`, no `key` and no `pad`, and `dev: true` on the dev serve),
909
+ `{ k: 'hub-cabinet', actor, door, card }` (v1.7: a cabinet's card for the door actor `actor`, `{ title, label, cover, top: [{ username, score, photo, frame }] }`, or `card: null` when it is gone),
910
+ `{ k: 'hub-arrived', facing }`, `{ k: 'hub-jumped', facing }` (after a jump to a door or, with `to` the player, to a player, §5),
911
+ `{ k: 'hub-party', members, away, invite, proposal }` (v1.10, on change: the other members here as player ids or null for no party, how many are away, `{ from, username }` or null, `{ id, door, by, username, asked }` or null, told only to the proposer and the members asked),
912
+ `{ k: 'hub-where', at }` (v1.9: player id → `{ x, z, where, door, on? }`, the ground spot to 0.1 m, the place's words or null, the door those words name or null, `on` true on its pad), `{ k: 'hub-hud', hud }` (that player's
913
+ override), `{ k: 'hub-tune', tune }` (v1.2, that player's `{ speed, jump }` or null), `{ k: 'hub-labels', labels }` (that player's own labels),
914
+ `{ k: 'hub-result', result }`, `{ k: 'hub-end', why }`,
915
+ `{ k: 'hub-grab-deny', actor }` (v1.3: a grab refused; let go), `{ k: 'hub-drop', actor }` (v1.3: `hub.drop`),
916
+ `{ k: 'hub-npc', npc, open, mind?, character?, name?, disclosure?, hearRange?, why? }` (since v1.17 `disclosure` is always `"participants"` and `hearRange` always 0: a client from before it named the players in that range as a turn's listeners),
917
+ `{ k: 'hub-npc-line', npc, text, why }` (`why` v1.8, as `npcLine`'s), `{ k: 'hub-npc-notes', npc, prefix }` (v1.8, §13), `{ k: 'hub-av', hubAv }` (avatars of players in a
918
+ hidden pair that this player may see, laid over the shared `hubAv`), `{ k: 'hub-wear', hubWear }`
919
+ (v1.4, their wearables, laid over the shared `hubWear` the same way).
920
+ Version-tagged by `hubPlace.contract`.
921
+
922
+ Blocks: two players a block hides from each other (either one blocked the
923
+ other; the host answers `session.hub.hiddenPair`, and the block lists never
924
+ reach the kit) are taken out of each other's interest sets whatever the
925
+ session's size, so neither is sent the other's pose rows or `in`; the shared
926
+ `hubAv` leaves out every player in such a pair, whose avatars go by `hub-av`
927
+ to each player who may see them. Words can name a player too: the shared `hud`
928
+ and `labels` carry no such player's username (it reads "someone") and no NPC
929
+ line about them, and each player gets the words they may read by `hub-hud` and
930
+ `hub-labels`, so nobody is sent a hidden partner's name, a late joiner's
931
+ WORLD included. An NPC conversation never admits a listener hidden from the
932
+ speaker, and its reply is checked again before it is shown. The host's roster, which
933
+ carries names, is already filtered per recipient. A session with no hidden pair
934
+ is sent exactly what it was.
935
+
936
+ Cabinet cards (v1.7). A card's pictures are data URIs, because a published
937
+ deck's page loads images from nowhere else, so a card is tens of kilobytes
938
+ (ghost keeps a board's `classic` to about 44 KB). The host refuses a frame to
939
+ a client over 64 KB and drops frames for the whole session past its send
940
+ budget (1 MB/s), so a card is never in the WORLD snapshot, a delta or a
941
+ broadcast. It is one `hub-cabinet` message to one player, one card a message,
942
+ sent when that player is within 14 m of the cabinet and does not have this
943
+ version of it; a card that changes goes again only to players in range then,
944
+ and to the others when they next come near. All cards together cost at most
945
+ 300 KB a second of the session's budget (180 KB in a burst), so a crowd
946
+ arriving at once is served over the following ticks. A card's frame is at most
947
+ 60 KB: over that the kit drops pictures -- frames, then photos, from the
948
+ bottom row up, then the cover -- as ghost does, and a picture that is not an
949
+ image data URI of at most 48 KB is left out; a row without a photo is drawn
950
+ with a placeholder. A client that joins afresh holds no cards and is sent them
951
+ again (its hello has no `again`). A row naming a player a block hides from the
952
+ viewer reads "someone" with no pictures (Blocks, above). The kit reads
953
+ cabinets' boards apart from the other doors', at most six to a read, since a
954
+ read answers in one frame of the host's channel. A place with no cabinet is
955
+ sent, and reads, exactly what it did.
956
+
957
+ Interest: in a session with more than `nearestPlayers` other players, each
958
+ client's `STATE` carries the rows of only the `nearestPlayers` players nearest
959
+ it (a player it already has counts as 20% nearer, so the set does not flicker),
960
+ plus `in` (players it starts being sent, each with its whole current row) and
961
+ `out` (players it stops being sent; the client shrinks their avatar away). The
962
+ WORLD snapshot carries the same set. While the session filters, a client is
963
+ sent other players' rows about 10 times a second (each its newest), its own
964
+ only as a correction, and every row's id as a short number: `idm` (`[[n,
965
+ playerId], ...]`) names each number the first time that client gets it, and
966
+ `pi` (ms) says how far apart the rows are, which the client draws others
967
+ behind by. Everything else -- objects, `hubAv` (but for Blocks, above),
968
+ `hud`, `held`, labels, pads and `hub.go` -- is still everyone's: only
969
+ drawing is filtered, and the server's simulation has every player. A
970
+ session no bigger than the set is sent one broadcast, as before.
971
+
972
+ ## 13. NPCs
973
+
974
+ HUB.md decision 7: an NPC's **body** is an actor in the place's session and its
975
+ **mind** is a character in ghost. A body is a scene actor with a kinematic
976
+ `Body` and a `HubNpc` component:
977
+
978
+ ```jsonc
979
+ "HubNpc": {
980
+ "name": "Rowan, the greeter", // shown on the Talk button, the panel and before every line
981
+ "character": "greeter", // optional: the castle.json characterBundle character that is its mind
982
+ "follow": "greeterFollow", // optional: the gameplay object whose holder the body follows
983
+ "talkRange": 3.5 // optional, metres (≤ 8)
984
+ // any other keys are the place's own (the town's `role`)
985
+ }
986
+ ```
987
+
988
+ **What the kit does with a body.** Near one, a player gets a Talk button (hub
989
+ chrome). Opening a conversation is the place server's decision: one player per
990
+ body at a time; another player gets the place's `busy` line. While a
991
+ conversation is open the body faces its speaker and holds still, through the
992
+ gaps between turns, until the player taps Done, walks more than 8 m away, leaves,
993
+ or says nothing for 90 s. Otherwise it walks where the place sends it, follows,
994
+ or faces what it was told to, in that order. Walking is a straight line at
995
+ 2.6 m/s with no navigation: put NPCs where a straight walk crosses nothing solid.
996
+
997
+ ```js
998
+ const npc = hub.npc('greeter'); // or hub.npcs()
999
+ npc.say('Welcome!'); // speech over it for everyone; { to: [playerIds] } for some
1000
+ npc.face(playerId); // or { x, z }, or null; while idle
1001
+ npc.walkTo({ x, z }, { stopAt: 0.4, then: () => … });
1002
+ npc.home(then?); // back where the scene put it, facing as it did
1003
+ npc.follow(playerId); // or null
1004
+ npc.stop(); // no walk, no follow
1005
+ npc.end(); // end its conversation
1006
+ npc.at; npc.talkingTo; npc.following; npc.walking; npc.busy; npc.props;
1007
+ ```
1008
+
1009
+ **Minds.** A place's minds live in a persistent world that carries the deck's
1010
+ shared characters (`docs/internal/shared-character-world-v1.md` in
1011
+ castle-experimental-web): `npcs.route` names one of `server.destinations`
1012
+ with `characters: "shared"` (so `selection: "exact"`, `persistence: "world"`),
1013
+ and the deck has a `characterBundle` whose `conversation` is
1014
+ `{ "version": 1, "authority": "server", "maxListeners": 0 }` (ghost admits a
1015
+ turn's audience only when the place's server, not a client, is the authority on
1016
+ it).
1017
+
1018
+ Minds are on every layer of the main place. A place's characters have one
1019
+ memory per place: ghost keeps a single place-mind record for the deck (keyed by
1020
+ its published character bundle, so a character change starts a new one), and
1021
+ every public layer of the main place addresses those characters by id, so what
1022
+ Rowan learns in one layer is known in the others and a player who changes layer
1023
+ keeps their history with him. On an SDK with place characters
1024
+ (`Multiplayer.placeCharacters`), the main place's client joins a layer like any
1025
+ other place, and the place's server reads the characters from
1026
+ `session.characters`; whether a layer gets them is ghost's and the host's call
1027
+ (the pilot is admin-gated, and an older host gives the layer authored lines).
1028
+ The `npcs.route` destination is the fallback for older SDKs: there the main
1029
+ place's client joins that route (`slot`, default `"main"`, is the world every
1030
+ player of the place shares) and the server reads `session.world.characters`.
1031
+ Only the main place either way, since every other place is reached through a
1032
+ door that names its own session.
1033
+
1034
+ | `npcs` field | rule |
1035
+ | --- | --- |
1036
+ | `route` | optional; a `server.destinations` route with `characters: "shared"`, joined only on SDKs without place characters. Without a route the minds are the place's alone: every layer addresses ghost's one place mind |
1037
+ | `slot` | 1-64 of `[A-Za-z0-9_.-]`; default `"main"`; the fallback route's world. A world keeps the character definitions it was created with: after changing the bundle's characters, name a new slot (ghost refuses turns in the old world with `CAULDRON_SHARED_CHARACTER_CONFLICT`) |
1038
+ | `turnsPerMinute` | 1-30, default 6: the conversation budget of each character's body, so per layer |
1039
+ | `disclosure` | `"participants"` or `"world"`: read, and since v1.17 not acted on. A player's conversation with a character is theirs alone (below) |
1040
+ | `followSec` | 10-600, default 120: how long a body follows before it goes home |
1041
+
1042
+ Where a session has the place's characters, a player's words are a character turn. The kit admits it only
1043
+ for the player the body is talking to, near it, with no listener of any kind,
1044
+ within the character's `turnsPerMinute`; anything else is refused
1045
+ before a model is called, and over budget the place's `budget` line answers
1046
+ instead, so a crowd degrades to authored lines rather than a queue. The reply
1047
+ is ghost's text, shown in the speaker's panel and over the body for the
1048
+ speaker alone.
1049
+
1050
+ **A player's conversation is theirs alone (v1.17).** What a player types to a
1051
+ character, and what the character answers, reaches no other player: not as a
1052
+ bubble, not through the character's memory, not in another layer or a later
1053
+ session. Ghost keeps a turn's words for everyone its audience names (a listener
1054
+ reads them back and the character may repeat them), so a turn names no player
1055
+ and no character as a listener and is never `world`-disclosed: the kit's
1056
+ client sends an empty audience, the kit's server refuses any other
1057
+ (`HUB_NPC_AUDIENCE`), and ghost keeps a place mind's conversations per player
1058
+ whatever a client sent. The character still remembers the same player
1059
+ tomorrow: its memory of them is that player's own. Only words with nothing of
1060
+ any player's typing in them are public: authored lines, ambient lines, and
1061
+ what a mind says from ghost's verified news. A place must keep it so: never
1062
+ put what a player typed (`npcHeard`'s and `npcLine`'s `text`) into a line, a
1063
+ label, a HUD, storage another player reads, or another player's notes.
1064
+ A body follows a player
1065
+ only when its character chose its follow action (an action whose object effect
1066
+ hands the `follow` object to `"player"`); clients cannot start or aim it. The
1067
+ follow object is one per place, so only the body in the holder's layer follows.
1068
+ No other character command reaches a hub place's characters in v1.
1069
+
1070
+ **Notes (v1.8).** A mind knows what its memory and the place's news tell it,
1071
+ not what the place knows this second (a quest-giver's ledger, the pad beside a
1072
+ barker). A place gives it that with `npcContext(hub, npc, playerId)`: the
1073
+ kit reads it for the speaker when a conversation opens and every second while
1074
+ it lasts, and sends the speaker's client `{ k: 'hub-npc-notes', npc, prefix }`
1075
+ when it changed, `prefix` being the notes framed by the kit
1076
+ (`[Notes from the place, ...]` ... `[The speaker says]`). The host forwards a
1077
+ player's words to ghost unaltered (the platform does not let the place's
1078
+ server rewrite a turn), so the client sends `prefix` ahead of the player's
1079
+ words, and the kit admits a turn only when its input starts with notes it
1080
+ issued that player for that body (the newest, or one of the last six within a
1081
+ minute), and the words after them frame no notes of their own; anything else
1082
+ is refused with `HUB_NPC_NOTES` and the client sends once more with the
1083
+ newest. A client can therefore leave its own words, but never the place's
1084
+ notes, out of true. The notes are part of the turn's input: ghost keeps them
1085
+ with the player's words as that player's conversation, so they should be facts
1086
+ about this player and this place, never another player's private state. The
1087
+ player's panel shows only their words. After a turn is admitted the kit calls
1088
+ `npcHeard(hub, npc, playerId, { text })` with the words alone. Without
1089
+ `npcContext` a turn is the words alone, as before.
1090
+
1091
+ Several bodies may share one character (one mind for every barker): a turn
1092
+ goes to the body its speaker is talking to.
1093
+
1094
+ **Authored lines.** Where a body has no mind -- no `npcs`, no `character`, or a
1095
+ session the host brokers no characters into (the dev serve; a host without
1096
+ place characters; on an older SDK, an account the route is not open to; the
1097
+ shared-character pilot is admin-gated) -- conversations still
1098
+ open and the place answers every turn from `npcLine(hub, npc, playerId, { why,
1099
+ text })`, with no model call. `why` is `"hello"` (a conversation opened),
1100
+ `"authored"` (the player said `text`), `"busy"`, `"budget"` or
1101
+ `"unavailable"`. Authored lines are the place's own words and go over the body
1102
+ for everyone. Where a body has a mind, `busy`, `budget` and `unavailable` lines
1103
+ answer in its place: the speaker's panel marks them as scripted (v1.8), and a
1104
+ place should have them acknowledge the player ("give me a moment") rather than
1105
+ answer a question they did not ask.
1106
+
1107
+ What a place's NPCs know of results. A place mind hears **verified** results
1108
+ as world news: ghost writes it from the recorded result row (a win, a new
1109
+ personal best: "Rowan won Foot Race in 1:02.4"), with usernames only and never
1110
+ stats or free text, so what a mind repeats is ghost's record, not a player's
1111
+ claim. Ghost publishes such news only for a player who is over 13, has
1112
+ share-what-I-play on, is not anonymous, and is not suspended, shadowbanned,
1113
+ multiplayer-banned or hub-banned. The news, and anything a mind says from it,
1114
+ never reaches anyone who blocks or is blocked by that player, never goes into a
1115
+ world-disclosed turn or to a listener ghost cannot identify, and never appears
1116
+ in public inspect, relays or a mind's autonomous decisions. Place code and authored lines are never handed a result as fact except
1117
+ what ghost verified: `hub.results` (§7) and a `carry.result` with
1118
+ `verified: true`. A carried result the client brought back on the dev serve
1119
+ (`verified: false`) is the client's word and is for display only.
1120
+
1121
+ ## 14. Per-player progress (v1.2)
1122
+
1123
+ A place that keeps a player's progress between visits keeps it in **deck
1124
+ scope keyed by the player's user id**: `hub.session.storage.deck` under
1125
+ `'<name>:<userId>'`, with the `userId` the kit hands it (`arrive`,
1126
+ `hub.players()`, `leave`). Never in user scope (`storage.user(userId)`): a
1127
+ player's own client can write that (`Store.me`), so progress kept there can be
1128
+ forged; only the deck's server writes deck scope. An anonymous player
1129
+ (`userId` null) has none, and the place says their progress is not kept.
1130
+ On the dev serve a guest's `userId` is its `dev-guest-<n>` subject.
1131
+ What the kit and Castle promise, and what they do not:
1132
+
1133
+ - **Load before you write.** A read that fails is not an empty save: a place
1134
+ that writes a fresh one after a failed read wipes the player's progress. Keep
1135
+ the player unsaved for the visit instead (Thornwall Escape and Lantern Lot do).
1136
+ - **Save as things change, not only at the end.** `leave` runs for every player
1137
+ who goes, while they are still known (their result is taken there too), and
1138
+ `shutdown` gives a stopping session a few seconds to finish its writes; but a
1139
+ host that fails sends neither. Write every few seconds, one write per account
1140
+ at a time, each carrying the whole save.
1141
+ - **Two visits can hold the same account** (two tabs, a late door), and deck
1142
+ storage has no compare-and-set: the last write wins. A place that must not
1143
+ lose progress to an older visit writes a counter it only ever raises and
1144
+ refuses to load over a newer one it has seen; a revision check in Castle's
1145
+ storage is filed as a platform gap.
1146
+ - **The dev serve:** guests (`dev-guest-<n>`) have storage only once the deck
1147
+ has been saved, and every serve reuses those subjects, so dev guests share
1148
+ their saves across runs; test persistence as the author, or clear the keys.
1149
+
1150
+ ## Changes from M0
1151
+
1152
+ | M0 gap | v1 |
1153
+ | --- | --- |
1154
+ | 1 no declared UI | §9 |
1155
+ | 2 server can't change an actor | §10 |
1156
+ | 3 can't hold a player | §8 |
1157
+ | 4 no shove | not in v1; engine rule, §6 |
1158
+ | 5 hooks lack the session | §4, `hub.session` |
1159
+ | 6 session doesn't know its place | §2 |
1160
+ | 7 results faked | §7, server-authored and validated; host forwarding is the hub.result card |
1161
+ | 8 avatar plumbing | §11, owned by the kit |
1162
+ | 9 arrival facing | §5, `arrival.face` |
1163
+
1164
+ ## Changes in v1
1165
+
1166
+ Minor additions, each optional; a deck written before them reads the same.
1167
+
1168
+ | date | change |
1169
+ | --- | --- |
1170
+ | 2026-10-04 (v1.22) | §1 and §6 `grab.reach` (1.6-3 m) and `grab.steady`: a place may offer objects from farther away and keep an offer up through a moment at its edge (the same object kept within the reach plus 0.4 m and 90 degrees of facing; the button held 600 ms through a lost owner or a turn; a press then waits 500 ms for the object to be this client's again), never past 3 m centre to centre. Sonnet playtests of Pillow Dojo and Number Pals on phones: the Grab button came and went at the reach, the cone and a shared owner, and bouts went on walking. Client only; a place without them is sent and drawn exactly what it was |
1171
+ | 2026-10-04 (v1.21) | §1 `tiers`: a deck may ask for device tiers, a cheaper picture drawn by a slow device's client (no sun shadow, decorative actors not drawn, scenery past 30 m and NPC bodies past 20 m not drawn) and a Graphics: Auto / Low / High row in the Character card. Phones the town was measured on (Galaxy Tab A7 Lite, Redmi 9A) drew it at 12 fps. Client only; a deck without `tiers` is drawn and behaves exactly as before |
1172
+ | 2026-10-04 (v1.20) | §5 a jump onto a pad (Doors Go, a party's go) is put on a spot no one stands within 1.1 m of (a ring 1.2 m about the pad's middle, at most half its radius, then a ring nearer its edge, then the middle, else the spot with the most room): a body put down touching another was pushed apart by physics and could push the one already there off the pad, so a pad that needed both never fired (production 18:00Z Oct 4). |
1173
+ | 2026-10-04 (v1.19) | §5 Join and starting beside a friend (`hub-goto`, an arrival's `near`) never place a player on a door's pad or within a body's width of one, the friend's own pad included: a friend on a pad is joined from just off its edge, facing them, so nobody is taken into a game they did not step into. With no clear spot off every pad the player stays where they were put. A place whose players never stand on pads sees no change |
1174
+ | 2026-10-04 (v1.18) | §5 a place replaced under its players: a place that is not a game, reached through a door, whose session ends under a player (a new version saved) sends them back the way they came with a line saying it was updated, instead of leaving them in its scene with no HUD, labels or controls; they walk in again through the door, into the new version. Also written down: the town at the root of the host's trail joins again where it stands (kit behaviour since 2026-10-04, not recorded until now). A game's ending is unchanged, and a deck changes nothing |
1175
+ | 2026-10-04 (v1.17) | §13 a player's conversation with a character is theirs alone: a turn names no listener (the client sends an empty audience and the server refuses any other), a mind's reply is drawn over the body for its speaker only (it was drawn for up to seven players within 6 m, and ghost kept the speaker's words for them too, so the character repeated them to those players later), `npcs.disclosure` is read and no longer acted on, and the Say panel's "Players nearby can hear" line is gone. Authored and ambient lines are public as before |
1176
+ | 2026-10-04 (v1.16) | §4 `hub.partyOf(playerId)`: the other members of a player's party who are in the place, so a place may wait for them (the town adds 7 s to a pad's countdown). §5 a Doors row carries `late: true` where the door takes late joiners; a friend who went through a door that does not is announced as "back soon" with no Follow |
1177
+ | 2026-10-04 (v1.15) | §5 in a town, the players who stay are told who went through which door (`hub-went`, §12: `{ players, door }`, never across a block, not for a cabinet); each client shows it only for its own friends and party members ("amy went into Tile Fall": Follow / Not now, for 45 s, Follow being a jump to that door's pad). A game sends none of it |
1178
+ | 2026-10-04 (v1.14) | §5 a town's Doors rows carry `featured` (listed first, starred), `solo` (a door that takes one player: a party is told so and is not asked to come) and `need` (its minimum when over one); a member who picks the door their party is already going to has answered yes; a friend or party member who comes in after the first moments is announced ("amy is here") and pointed to. §6 the chat field is always shown where the host has chat, disabled with the reason when it cannot be used ("Follow each other to chat. Nobody here follows you back yet.", "Chat isn't available on this account"). A deck changes nothing |
1179
+ | 2026-10-04 (v1.13) | §10 goals: `hub.label`'s `style: "goal"`, a per-player pointer to a scene actor drawn at the screen's edge while it is out of view. Pebble Cove's playtesters could not find the villager an errand named: a sign is drawn only where it projects on screen, and the camera looks down. A place that sets no goal is drawn exactly as before |
1180
+ | 2026-10-03 (v1.12) | §6 free-text chat between players who follow each other and are both over 13, enforced by ghost through the host (`Hub.chat`, `Hub.say`, `Hub.reportChat`); the kit draws what it is handed and says only "Follow each other to chat" otherwise. Nothing on the place's wire, and nothing at all on a host without the commands |
1181
+ | 2026-10-03 (v1.11) | §4 layer doors: `HubDoor` gains the optional `kind: "layer"` for a door whose row places on layers; `hub.go` on it tells each signed-in player to go with no pad, and `hub.pad` tells ghost nothing. The first place with its own minds behind a door (Pebble Cove) needed it: only a public layer gets a place's minds, and a town could only fire pads. A place with no such door behaves exactly as before |
1182
+ | 2026-10-03 (v1.11) | §6 quick reactions and phrases: the speech button, `hub-say` and `hub-said` (§12), in every hub place; the avatar picker is one Character button that opens the characters; a town's Doors list leaves an event gate out while its event is closed and names it "Event · <title>" while open. A deck changes nothing |
1183
+ | 2026-10-03 (v1.10) | §5 parties in a town: invite and accept, Join to a member, Doors > Go proposes the door to the party and puts each member who says yes on its pad; `hub-party` both ways (§12), `hub.coming` (§4). A jump to a door lands on its pad where it has one (it was 7 m in front). A game has none of it; a town that reads no `hub.coming` fires its pads as before |
1184
+ | 2026-10-03 (v1.9) | §5 finding a friend: the People list in a town names everyone with where they are, friends first with Join, the rest with Find (a pointer); `hub-where`, `hub-goto` (§12), the `where` hook (§4), pointers to friends out of sight; the Friends button is gone (its friends are in the People list). A game lists what it did, and a deck changes nothing; a town on a host without `Hub.friends` lists names only |
1185
+ | 2026-10-03 (v1.8) | §13 notes: the `npcContext` and `npcHeard` hooks, `hub-npc-notes` and the notes prefix a mind's turn carries (`HUB_NPC_NOTES` for any other); bodies sharing a character; `hub-npc-line` carries `why`, and the panel marks a mind's scripted answers. A place with neither hook sends turns and is sent what it was, but for the panel's mark |
1186
+ | 2026-10-03 | §10 labels in a town (a place with no `result`): only the nearest plate within 4 m and the nearest NPC line within 9 m are drawn, and other players' names within 12 m, smaller; `hub.label`'s `style: "sign"` is drawn at any distance (an older client draws it as a tag). The contract's calls are unchanged; a game place draws exactly what it did |
1187
+ | 2026-10-03 | §4 a cabinet's card is a chip by default (the best score and whose it is), drawn within 5 m instead of 9; the whole board opens on a tap and closes on a tap or on walking away. What the server sends is unchanged |
1188
+ | 2026-10-03 (v1.7) | §4 cabinets: a door to a classic Castle deck. `hub.doors()` entries gain `classic`; `hub.go` on such a door tells each player's client to go alone (`hub-go` with `classic`) instead of firing a pad; `HubDoor` gains the optional `kind: "cabinet"` (no swing, not in the Doors list, no pad with ghost). §5 the cabinet's trip: `Hub.go` answered `kind: 'classic'`, then away under the cover, out of the session, until the ordinary `Hub.back`. §12 `hub-cabinet` (a card, per player, in range, once per version, budgeted), `hub-dev-classic`, and `again` on a repeated hello. A place with no cabinet draws nothing new and is sent and reads exactly what it did; a host that does not answer `kind: 'classic'` keeps the door shut |
1189
+ | 2026-10-03 (v1.6) | §6 a place's sounds play in a game reached through a door: the content pack carries the files its places' `idle.sounds` list (`audio`, `docs/content-pack.md`), and the town's engine plays them from there. A deck changes nothing; a town on an older engine ignores `audio`, and the game is silent there as before |
1190
+ | 2026-10-03 (v1.6) | §6 idle play: the `idle` manifest field; emotes (`hub-emote`, the `emote` hook, `hub.emote`), seats (`HubSeat` actors, `hub-sit` / `hub-stand`, the `sit` hook, `hub.seat`; a seat is a §8 hold) and the place's sounds (`hub.sound`, its own deck's files); `hubEmotes`, `hubSeated`, `hubSounds` and `hub-sound` (§12). The M2 town's benches could only be stood by and its jukebox played lamp colours. A place without `idle` draws nothing new and is sent exactly what it was |
1191
+ | 2026-10-03 (v1.5) | §7 `hub.results(playerId)`: ghost's recent results and records of a player, read at arrival and once a minute. The town's innkeeper read them through the host's results read beside the kit's own |
1192
+ | 2026-10-03 (v1.4) | §11 `hub.wear`: a wearable `{ kind, color, rarity }` on the player's avatar, kept by ghost per account (from a curated place) and drawn in every hub place; `hubWear` and `hub-wear` (§12). M3's Wishwell rolled an aura it could only draw in its own scene. A place where nobody wears anything is sent exactly what it was; `hubAv` is unchanged |
1193
+ | 2026-10-03 | Blocks hide players both ways (§12 `hub-av`); the hub chrome's People list reports a player (`Hub.report`) where the host runs the hub; a player barred from the hub (`CAULDRON_HUB_BANNED`) is told "You can't enter the town right now." and not retried. A deck changes nothing, and a session with no blocks is sent what it was |
1194
+ | 2026-10-03 | §12 a filtering session sends other players' rows at ~10 Hz with short ids (`idm`, `pi`). A session within `nearestPlayers` is sent what it was |
1195
+ | 2026-10-03 | §5 jumping to a door: a town's Doors button beside Friends, `hubDoors` and `hub-door-jump` (§12). A game draws nothing new, and a deck changes nothing |
1196
+ | 2026-10-03 | §4 a door may face any way: the trip's swing and camera follow its rotationY. A door facing +z (every M1 door) swings and films exactly as before |
1197
+ | 2026-10-02 | `nearestPlayers` and the `in`/`out` interest fields (§12). A session of 31 players or fewer is sent exactly what it was |
1198
+ | 2026-10-02 | §5 joining a friend: the Friends button and `Hub.jump`, drawn only where the host answers `Hub.friends`. A game (a place with `result`) never shows it, and nothing changes for a deck |
1199
+ | 2026-10-02 | §13 NPCs: `HubNpc` bodies, `hub.npc`, `npcLine`, the `npcs` manifest field; `hub.label` gains `to`. A place that uses none of them is drawn and behaves exactly as before |
1200
+ | 2026-10-03 (v1.3) | §10 `hub.pose` and `hub.reset`: read a body and put a loose object back, taking it from the client simulating it with a handover. M3's Bumper Ball kept a pool of eight hidden balls because nothing could put one back on the spot, and read positions out of `hub.sim` |
1201
+ | 2026-10-03 (v1.3) | §6 grabbing and throwing: the `grab` manifest field, the `grab` hook, `hub.drop` and `hub.holding` (§4), the hub chrome's Grab / Throw button, `hub-grab`, `hub-grab-deny` and `hub-drop` (§12). M3's Bumper Ball wanted Fling Things and could only shove props by walking into them. A place without `grab` draws nothing new and is sent exactly what it was |
1202
+ | 2026-10-03 (v1.2) | §4 `hub.board` carries `featured` (today's rotation features the door) and, on an event gate, `event` (`day`, `open`, `opensAt`, `closesAt`, `last`), where ghost has them. The M2 town could not mark featured doors or run its 8pm event gate; a place that reads neither is unchanged |
1203
+ | 2026-10-03 (v1.2) | §4 `userId` on `arrive`, `hub.players()` and `leave`; `leave` runs while the player is known, so it may report their result; a `shutdown` hook; §14 per-player progress. M3's Lantern Lot and Thornwall Escape read user ids out of the session, lost a Back-leaving player's result, and could lose a last save at shutdown |
1204
+ | 2026-10-03 (v1.2) | §6 `hub.tune`, told to its player as `hub-tune` (§12); multiplayer-3d's clamp reads a player's own `maxSpeed`. M3's Thornwall Escape could not make the stat it grows make anyone faster, so the stat only opened gates |
1205
+ | 2026-10-03 (v1.2) | §10 `hub.spawn` and `hub.despawn`, carried as `spawned` (§12). M3's Lantern Lot authored every lantern of every kind on every slot, plus a carried copy per lot per kind, and hid them (230 actors, a 108 KB pack); with templates it has 90. A hidden kinematic actor is now hidden on every client (it was drawn at its network pose) |
1206
+ | 2026-10-02 (v1.1) | §7 a result's `outcome` is optional when it carries a score; §5 `fallY`, the `fall` hook and scenes with no ground (`"ground": { "none": true }`, physics-3d and multiplayer-3d); §4 a dev `deck:<name>` door reads the destination's castle.json, and the check refuses drift. M1's Summit Sprint and Vault Crew called finishing a win; Tile Fall faked its lava with pillars over a coloured ground |
1207
+ | 2026-10-02 (v1.1) | §11 `hub.mark`, carried as `marks` (§12). M1's Zone Wars could not show anyone's team and Tag could not show who was it |
1208
+ | 2026-10-02 (v1.1) | §13 minds on every layer: on an SDK with `Multiplayer.placeCharacters` the main place joins a layer and its NPCs read `session.characters`, one memory per place; `npcs.route` is the fallback for older SDKs. A deck without `npcs` is unchanged |
1209
+ | 2026-10-02 (v1.1) | §10 `hub.move` and `hub.tint`; §4 `hub.actorsWith` adds `shape` and `body`. The snapshot carries `tints` (§12). M1's Vault Crew and Tile Fall said a plate's or tile's state with labels and could not have a moving platform; Zone Wars and Summit Sprint repeated each zone's and pillar's size in its marker |