castle-web-cli 0.4.228 → 0.4.230

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