castle-web-cli 0.4.232 → 0.4.234

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 (587) hide show
  1. package/dist/agent-failures.d.ts +8 -0
  2. package/dist/agent-failures.js +19 -2
  3. package/dist/agent-prompts.d.ts +1 -1
  4. package/dist/agent-prompts.js +10 -3
  5. package/dist/agent.d.ts +64 -3
  6. package/dist/agent.js +170 -81
  7. package/dist/api.d.ts +11 -0
  8. package/dist/api.js +43 -0
  9. package/dist/bundle.d.ts +64 -0
  10. package/dist/bundle.js +558 -2
  11. package/dist/castle-host/host.d.ts +18 -2
  12. package/dist/castle-host/host.js +844 -39
  13. package/dist/castleJson.d.ts +23 -2
  14. package/dist/castleJson.js +46 -2
  15. package/dist/check.d.ts +3 -1
  16. package/dist/check.js +20 -3
  17. package/dist/chunkLoader.d.ts +3 -0
  18. package/dist/chunkLoader.js +111 -0
  19. package/dist/devParty.d.ts +26 -0
  20. package/dist/devParty.js +231 -0
  21. package/dist/devSaveStorage.js +4 -0
  22. package/dist/devSessionStorage.js +50 -2
  23. package/dist/devSocial.d.ts +24 -0
  24. package/dist/devSocial.js +70 -0
  25. package/dist/ide.d.ts +2 -0
  26. package/dist/ide.js +119 -15
  27. package/dist/importPinMismatch.d.ts +22 -0
  28. package/dist/importPinMismatch.js +77 -0
  29. package/dist/importRegression.js +3 -15
  30. package/dist/imports.d.ts +10 -3
  31. package/dist/imports.js +88 -20
  32. package/dist/index.js +11 -4
  33. package/dist/init.js +1 -1
  34. package/dist/platformDoc.js +22 -0
  35. package/dist/routerFences.d.ts +5 -0
  36. package/dist/routerFences.js +12 -2
  37. package/dist/save-deck.d.ts +25 -1
  38. package/dist/save-deck.js +178 -9
  39. package/dist/serve.js +32 -11
  40. package/dist/shell/assets/{index-D2tWM896.js → index-DulbYIJm.js} +97 -97
  41. package/dist/shell/assets/index-MVLfNYd9.css +1 -0
  42. package/dist/shell/index.html +2 -2
  43. package/dist/taskSteer.d.ts +13 -0
  44. package/dist/taskSteer.js +22 -2
  45. package/dist/vitePlugins.d.ts +2 -1
  46. package/dist/vitePlugins.js +13 -0
  47. package/kits/base/castle.json +1 -1
  48. package/kits/base/package-lock.json +1 -1
  49. package/kits/base/sdk/README.md +339 -5
  50. package/kits/base/sdk/avatar.d.ts +6 -2
  51. package/kits/base/sdk/avatar.js +12 -4
  52. package/kits/base/sdk/castle.d.ts +7 -3
  53. package/kits/base/sdk/castle.js +2 -0
  54. package/kits/base/sdk/commands.d.ts +176 -1
  55. package/kits/base/sdk/commands.js +3 -0
  56. package/kits/base/sdk/display.d.ts +3 -0
  57. package/kits/base/sdk/display.js +9 -3
  58. package/kits/base/sdk/hub.d.ts +37 -6
  59. package/kits/base/sdk/hub.js +63 -4
  60. package/kits/base/sdk/multiplayer.d.ts +7 -1
  61. package/kits/base/sdk/multiplayer.js +148 -32
  62. package/kits/base/sdk/multiplayerProtocol.d.ts +2 -0
  63. package/kits/base/sdk/party.d.ts +23 -0
  64. package/kits/base/sdk/party.js +91 -0
  65. package/kits/base/sdk/reconnectBudget.d.ts +23 -0
  66. package/kits/base/sdk/reconnectBudget.js +96 -0
  67. package/kits/base/sdk/save.d.ts +38 -1
  68. package/kits/base/sdk/save.js +81 -7
  69. package/kits/base/sdk/server/hub.d.ts +117 -0
  70. package/kits/base/sdk/server/hub.js +119 -2
  71. package/kits/base/sdk/server/platformHandle.d.ts +43 -1
  72. package/kits/base/sdk/server/storage.d.ts +17 -0
  73. package/kits/base/sdk/server/storage.js +65 -3
  74. package/kits/base/sdk/server/wrapper.d.ts +43 -6
  75. package/kits/base/sdk/server/wrapper.js +93 -9
  76. package/kits/base/sdk/social.d.ts +9 -0
  77. package/kits/base/sdk/social.js +5 -0
  78. package/kits/hub-game/CLAUDE.md +451 -13
  79. package/kits/hub-game/README.md +63 -0
  80. package/kits/hub-game/blueprints/avatar-10.scene +28 -0
  81. package/kits/hub-game/blueprints/avatar-11.scene +28 -0
  82. package/kits/hub-game/blueprints/avatar-12.scene +28 -0
  83. package/kits/hub-game/blueprints/avatar-13.scene +28 -0
  84. package/kits/hub-game/blueprints/avatar-14.scene +28 -0
  85. package/kits/hub-game/blueprints/avatar-15.scene +28 -0
  86. package/kits/hub-game/blueprints/avatar-4.scene +28 -0
  87. package/kits/hub-game/blueprints/avatar-5.scene +28 -0
  88. package/kits/hub-game/blueprints/avatar-6.scene +28 -0
  89. package/kits/hub-game/blueprints/avatar-7.scene +28 -0
  90. package/kits/hub-game/blueprints/avatar-8.scene +28 -0
  91. package/kits/hub-game/blueprints/avatar-9.scene +28 -0
  92. package/kits/hub-game/castle.json +5 -5
  93. package/kits/hub-game/code/client/act.js +312 -0
  94. package/kits/hub-game/code/client/actionLayout.js +147 -0
  95. package/kits/hub-game/code/client/actionOverflow.js +556 -0
  96. package/kits/hub-game/code/client/actorBudget.js +47 -0
  97. package/kits/hub-game/code/client/arrivalCamera.js +50 -0
  98. package/kits/hub-game/code/client/askSlot.js +117 -0
  99. package/kits/hub-game/code/client/attention.js +11 -2
  100. package/kits/hub-game/code/client/avatar.js +311 -35
  101. package/kits/hub-game/code/client/avatarCap.js +228 -0
  102. package/kits/hub-game/code/client/avatarColors.js +70 -0
  103. package/kits/hub-game/code/client/avatarFaces.js +21 -0
  104. package/kits/hub-game/code/client/avatarShare.js +253 -0
  105. package/kits/hub-game/code/client/backVisibility.js +13 -0
  106. package/kits/hub-game/code/client/ballot.js +472 -0
  107. package/kits/hub-game/code/client/build.js +38 -0
  108. package/kits/hub-game/code/client/chat.js +41 -5
  109. package/kits/hub-game/code/client/chatModeration.js +5 -0
  110. package/kits/hub-game/code/client/chrome.js +2144 -160
  111. package/kits/hub-game/code/client/companion.js +716 -0
  112. package/kits/hub-game/code/client/companionDress.js +99 -0
  113. package/kits/hub-game/code/client/crowdNames.js +241 -0
  114. package/kits/hub-game/code/client/decor.js +515 -0
  115. package/kits/hub-game/code/client/defaultEnvironment.js +194 -0
  116. package/kits/hub-game/code/client/doorErrors.js +39 -0
  117. package/kits/hub-game/code/client/earned.js +131 -0
  118. package/kits/hub-game/code/client/emoteBubble.js +75 -0
  119. package/kits/hub-game/code/client/fall.js +18 -0
  120. package/kits/hub-game/code/client/farAvatars.js +233 -0
  121. package/kits/hub-game/code/client/firstJoin.js +9 -2
  122. package/kits/hub-game/code/client/fpsTelemetry.js +50 -0
  123. package/kits/hub-game/code/client/frameBatch.js +5 -0
  124. package/kits/hub-game/code/client/grab.js +368 -29
  125. package/kits/hub-game/code/client/hookLayer.js +385 -20
  126. package/kits/hub-game/code/client/hudCopy.js +51 -0
  127. package/kits/hub-game/code/client/hudRate.js +20 -0
  128. package/kits/hub-game/code/client/idle.js +177 -24
  129. package/kits/hub-game/code/client/interestCap.js +81 -0
  130. package/kits/hub-game/code/client/invites.js +231 -0
  131. package/kits/hub-game/code/client/joinError.js +9 -0
  132. package/kits/hub-game/code/client/keys.js +36 -0
  133. package/kits/hub-game/code/client/labelsNear.js +234 -0
  134. package/kits/hub-game/code/client/landscapeLayout.js +17 -0
  135. package/kits/hub-game/code/client/layoutCache.js +264 -0
  136. package/kits/hub-game/code/client/loadTelemetry.js +20 -0
  137. package/kits/hub-game/code/client/loadingCover.js +148 -0
  138. package/kits/hub-game/code/client/loadingEntry.js +8 -0
  139. package/kits/hub-game/code/client/menuIcons.js +34 -0
  140. package/kits/hub-game/code/client/menuRows.js +43 -0
  141. package/kits/hub-game/code/client/modelReady.js +7 -0
  142. package/kits/hub-game/code/client/pack.js +6 -2
  143. package/kits/hub-game/code/client/packFormat.js +3 -3
  144. package/kits/hub-game/code/client/padCueArrival.js +23 -0
  145. package/kits/hub-game/code/client/padCues.js +112 -0
  146. package/kits/hub-game/code/client/padOccupancy.js +88 -0
  147. package/kits/hub-game/code/client/padReadability.js +26 -0
  148. package/kits/hub-game/code/client/padRings.js +69 -0
  149. package/kits/hub-game/code/client/pushVisit.js +14 -0
  150. package/kits/hub-game/code/client/quality.js +205 -0
  151. package/kits/hub-game/code/client/qualityEntry.js +55 -0
  152. package/kits/hub-game/code/client/rehello.js +167 -0
  153. package/kits/hub-game/code/client/safeLayout.js +338 -0
  154. package/kits/hub-game/code/client/safeStyle.js +42 -0
  155. package/kits/hub-game/code/client/say.js +12 -3
  156. package/kits/hub-game/code/client/shot.js +146 -0
  157. package/kits/hub-game/code/client/shotFit.js +56 -0
  158. package/kits/hub-game/code/client/signIn.js +28 -0
  159. package/kits/hub-game/code/client/sound.js +63 -8
  160. package/kits/hub-game/code/client/soundscape.js +1151 -0
  161. package/kits/hub-game/code/client/soundscapeActions.js +99 -0
  162. package/kits/hub-game/code/client/soundscapeAmbience.js +453 -0
  163. package/kits/hub-game/code/client/soundscapeBaked.js +143 -0
  164. package/kits/hub-game/code/client/soundscapeBusker.js +217 -0
  165. package/kits/hub-game/code/client/soundscapeCourt.js +200 -0
  166. package/kits/hub-game/code/client/soundscapeCrowd.js +331 -0
  167. package/kits/hub-game/code/client/soundscapeCues.js +362 -0
  168. package/kits/hub-game/code/client/soundscapeMap.js +181 -0
  169. package/kits/hub-game/code/client/soundscapeMarket.js +176 -0
  170. package/kits/hub-game/code/client/soundscapeMusic.js +126 -0
  171. package/kits/hub-game/code/client/soundscapeMusicEngine.js +460 -0
  172. package/kits/hub-game/code/client/soundscapeSimlish.js +737 -0
  173. package/kits/hub-game/code/client/soundscapeSongs.js +127 -0
  174. package/kits/hub-game/code/client/soundscapeSongsRound3.js +63 -0
  175. package/kits/hub-game/code/client/soundscapeSynthesis.js +168 -0
  176. package/kits/hub-game/code/client/soundscapeUi.js +211 -0
  177. package/kits/hub-game/code/client/soundscapeVoice.js +1209 -0
  178. package/kits/hub-game/code/client/soundscapeWaves.js +206 -0
  179. package/kits/hub-game/code/client/spin.js +101 -0
  180. package/kits/hub-game/code/client/state.js +162 -1
  181. package/kits/hub-game/code/client/stuck.js +259 -0
  182. package/kits/hub-game/code/client/talk.js +714 -59
  183. package/kits/hub-game/code/client/tiers.js +543 -52
  184. package/kits/hub-game/code/client/toastBand.js +37 -0
  185. package/kits/hub-game/code/client/together.js +39 -2
  186. package/kits/hub-game/code/client/visibility.js +43 -0
  187. package/kits/hub-game/code/client/weakestLookBake.js +92 -0
  188. package/kits/hub-game/code/client/weakestTier.js +295 -0
  189. package/kits/hub-game/code/client/wear.js +461 -170
  190. package/kits/hub-game/code/client/worldLabels.js +241 -0
  191. package/kits/hub-game/code/client/yours.js +200 -0
  192. package/kits/hub-game/code/companionSpec.js +45 -0
  193. package/kits/hub-game/code/npcDisplayText.js +55 -0
  194. package/kits/hub-game/code/privateText.js +7 -0
  195. package/kits/hub-game/code/server/act.js +124 -0
  196. package/kits/hub-game/code/server/actions.js +138 -0
  197. package/kits/hub-game/code/server/actors.js +11 -2
  198. package/kits/hub-game/code/server/analytics.js +83 -0
  199. package/kits/hub-game/code/server/anonymousEntry.js +49 -0
  200. package/kits/hub-game/code/server/arrivalPose.js +36 -0
  201. package/kits/hub-game/code/server/ask.js +155 -0
  202. package/kits/hub-game/code/server/ballot.js +539 -0
  203. package/kits/hub-game/code/server/cells.js +100 -0
  204. package/kits/hub-game/code/server/companion.js +107 -0
  205. package/kits/hub-game/code/server/cues.js +70 -0
  206. package/kits/hub-game/code/server/decor.js +269 -0
  207. package/kits/hub-game/code/server/doorAnalytics.js +52 -0
  208. package/kits/hub-game/code/server/earned.js +478 -0
  209. package/kits/hub-game/code/server/frameBatch.js +183 -0
  210. package/kits/hub-game/code/server/friendBests.js +166 -0
  211. package/kits/hub-game/code/server/friendsAmong.js +272 -0
  212. package/kits/hub-game/code/server/history.js +7 -0
  213. package/kits/hub-game/code/server/hub.js +2510 -95
  214. package/kits/hub-game/code/server/idle.js +60 -12
  215. package/kits/hub-game/code/server/index.js +28 -6
  216. package/kits/hub-game/code/server/invites.js +19 -0
  217. package/kits/hub-game/code/server/labels.js +36 -2
  218. package/kits/hub-game/code/server/loadAbandon.js +106 -0
  219. package/kits/hub-game/code/server/manifest.js +586 -7
  220. package/kits/hub-game/code/server/menu.js +161 -0
  221. package/kits/hub-game/code/server/npcs.js +1025 -113
  222. package/kits/hub-game/code/server/observe.js +408 -0
  223. package/kits/hub-game/code/server/padOccupancy.js +85 -0
  224. package/kits/hub-game/code/server/party.js +2 -2
  225. package/kits/hub-game/code/server/players.js +30 -0
  226. package/kits/hub-game/code/server/resumePose.js +152 -0
  227. package/kits/hub-game/code/server/say.js +1 -1
  228. package/kits/hub-game/code/server/shot.js +110 -0
  229. package/kits/hub-game/code/server/standing.js +123 -0
  230. package/kits/hub-game/code/server/storageLimit.js +187 -0
  231. package/kits/hub-game/code/server/vis.js +175 -0
  232. package/kits/hub-game/code/server/wear.js +12 -0
  233. package/kits/hub-game/code/server/yours.js +59 -0
  234. package/kits/hub-game/code/shared/act.js +35 -0
  235. package/kits/hub-game/code/shared/cues.js +9 -0
  236. package/kits/hub-game/code/shared/danceIdle.js +28 -0
  237. package/kits/hub-game/code/shared/decor.js +41 -0
  238. package/kits/hub-game/code/shared/loadStages.js +12 -0
  239. package/kits/hub-game/code/shared/quality.js +74 -0
  240. package/kits/hub-game/code/shared/say.js +2 -0
  241. package/kits/hub-game/code/shared/shot.js +53 -0
  242. package/kits/hub-game/code/shared/spin.js +57 -0
  243. package/kits/hub-game/code/systems/hub.js +1753 -202
  244. package/kits/hub-game/docs/analytics.md +279 -0
  245. package/kits/hub-game/docs/content-pack.md +1 -1
  246. package/kits/hub-game/docs/contract.md +3475 -77
  247. package/kits/hub-game/docs/home-pieces.md +71 -0
  248. package/kits/hub-game/docs/observed-progress.md +252 -0
  249. package/kits/hub-game/main.jsx +2 -0
  250. package/kits/hub-game/models/avatar-10.pxmodel +28 -0
  251. package/kits/hub-game/models/avatar-11.pxmodel +28 -0
  252. package/kits/hub-game/models/avatar-12.pxmodel +27 -0
  253. package/kits/hub-game/models/avatar-13.pxmodel +24 -0
  254. package/kits/hub-game/models/avatar-14.pxmodel +29 -0
  255. package/kits/hub-game/models/avatar-15.pxmodel +24 -0
  256. package/kits/hub-game/models/avatar-4.pxmodel +29 -0
  257. package/kits/hub-game/models/avatar-5.pxmodel +27 -0
  258. package/kits/hub-game/models/avatar-6.pxmodel +26 -0
  259. package/kits/hub-game/models/avatar-7.pxmodel +25 -0
  260. package/kits/hub-game/models/avatar-8.pxmodel +24 -0
  261. package/kits/hub-game/models/avatar-9.pxmodel +30 -0
  262. package/kits/hub-game/models/earned/badge-round.pxmodel +100 -0
  263. package/kits/hub-game/models/earned/badge-shield.pxmodel +117 -0
  264. package/kits/hub-game/models/earned/badge-star.pxmodel +87 -0
  265. package/kits/hub-game/models/earned/belt-plain.pxmodel +72 -0
  266. package/kits/hub-game/models/earned/held-ball.pxmodel +43 -0
  267. package/kits/hub-game/models/earned/held-lantern.pxmodel +85 -0
  268. package/kits/hub-game/models/earned/held-net.pxmodel +57 -0
  269. package/kits/hub-game/models/earned/held-trophy.pxmodel +109 -0
  270. package/kits/hub-game/models/earned/pin-round.pxmodel +62 -0
  271. package/kits/hub-game/models/earned/sash-plain.pxmodel +66 -0
  272. package/kits/hub-game/models/earned/square/belt-plain.pxmodel +104 -0
  273. package/kits/hub-game/models/earned/square/sash-plain.pxmodel +98 -0
  274. package/kits/hub-game/models/hats/bat-clip.pxmodel +206 -0
  275. package/kits/hub-game/models/hats/beekeeper.pxmodel +149 -0
  276. package/kits/hub-game/models/hats/cap.pxmodel +162 -0
  277. package/kits/hub-game/models/hats/captain.pxmodel +178 -0
  278. package/kits/hub-game/models/hats/crooked-top.pxmodel +172 -0
  279. package/kits/hub-game/models/hats/flower-crown.pxmodel +451 -0
  280. package/kits/hub-game/models/hats/foam-crown.pxmodel +179 -0
  281. package/kits/hub-game/models/hats/lantern.pxmodel +230 -0
  282. package/kits/hub-game/models/hats/laurel.pxmodel +533 -0
  283. package/kits/hub-game/models/hats/lighthouse.pxmodel +96 -0
  284. package/kits/hub-game/models/hats/sailor.pxmodel +141 -0
  285. package/kits/hub-game/models/hats/souwester.pxmodel +131 -0
  286. package/kits/hub-game/models/hats/straw.pxmodel +139 -0
  287. package/kits/hub-game/models/hats/sunflower.pxmodel +406 -0
  288. package/kits/hub-game/models/hats/sweatband.pxmodel +112 -0
  289. package/kits/hub-game/models/hats/witch.pxmodel +147 -0
  290. package/kits/hub-game/package-lock.json +10 -1
  291. package/kits/hub-game/package.json +6 -2
  292. package/kits/hub-game/play/player.js +142 -0
  293. package/kits/hub-game/play/registry.js +47 -0
  294. package/kits/hub-game/play.jsx +37 -0
  295. package/kits/hub-game/scripts/check.mjs +117 -16
  296. package/kits/hub-game/scripts/companion-follower-wire.json +1 -0
  297. package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +132 -0
  298. package/kits/hub-game/scripts/fixtures/decor-keyless.json +293 -0
  299. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +26 -0
  300. package/kits/hub-game/scripts/fixtures/fake-dom.mjs +123 -0
  301. package/kits/hub-game/scripts/fixtures/interest-legacy.json +385 -0
  302. package/kits/hub-game/scripts/fixtures/npc-notes-v1.77.jsonl +4 -0
  303. package/kits/hub-game/scripts/fixtures/vis-shared-wire.json +1 -0
  304. package/kits/hub-game/scripts/gen-avatars.mjs +933 -16
  305. package/kits/hub-game/scripts/gen-earned.mjs +285 -0
  306. package/kits/hub-game/scripts/gen-hats.mjs +827 -0
  307. package/kits/hub-game/scripts/grab.before-orbit.mjs +400 -0
  308. package/kits/hub-game/scripts/pose-storage-fixture.mjs +46 -0
  309. package/kits/hub-game/scripts/soundscape-wave-analysis.mjs +125 -0
  310. package/kits/hub-game/scripts/test-act-client.mjs +186 -0
  311. package/kits/hub-game/scripts/test-act.mjs +171 -0
  312. package/kits/hub-game/scripts/test-action-layout.mjs +80 -0
  313. package/kits/hub-game/scripts/test-action-observers.mjs +46 -0
  314. package/kits/hub-game/scripts/test-actions-client.mjs +853 -0
  315. package/kits/hub-game/scripts/test-actions.mjs +298 -0
  316. package/kits/hub-game/scripts/test-actor-budget.mjs +44 -0
  317. package/kits/hub-game/scripts/test-actors.mjs +38 -23
  318. package/kits/hub-game/scripts/test-analytics.mjs +76 -0
  319. package/kits/hub-game/scripts/test-anonymous-entry.mjs +28 -0
  320. package/kits/hub-game/scripts/test-arrival-pose-server.mjs +196 -0
  321. package/kits/hub-game/scripts/test-arrival-pose.mjs +24 -0
  322. package/kits/hub-game/scripts/test-ask-client.mjs +358 -0
  323. package/kits/hub-game/scripts/test-ask-slot.mjs +85 -0
  324. package/kits/hub-game/scripts/test-ask.mjs +269 -0
  325. package/kits/hub-game/scripts/test-attention.mjs +10 -1
  326. package/kits/hub-game/scripts/test-avatar-cap.mjs +379 -0
  327. package/kits/hub-game/scripts/test-avatar-colors.mjs +72 -0
  328. package/kits/hub-game/scripts/test-avatar-models.mjs +181 -0
  329. package/kits/hub-game/scripts/test-avatar-share.mjs +318 -0
  330. package/kits/hub-game/scripts/test-avatar-wire.mjs +792 -0
  331. package/kits/hub-game/scripts/test-avatar.mjs +584 -7
  332. package/kits/hub-game/scripts/test-back-visibility.mjs +82 -0
  333. package/kits/hub-game/scripts/test-ballot.mjs +1008 -0
  334. package/kits/hub-game/scripts/test-ban-join.mjs +121 -13
  335. package/kits/hub-game/scripts/test-build.mjs +49 -0
  336. package/kits/hub-game/scripts/test-cells.mjs +71 -0
  337. package/kits/hub-game/scripts/test-chat.mjs +863 -0
  338. package/kits/hub-game/scripts/test-classic.mjs +2 -0
  339. package/kits/hub-game/scripts/test-companion-chat.mjs +216 -0
  340. package/kits/hub-game/scripts/test-companion-client.mjs +1167 -0
  341. package/kits/hub-game/scripts/test-companion.mjs +259 -0
  342. package/kits/hub-game/scripts/test-control-layout-dom.mjs +120 -0
  343. package/kits/hub-game/scripts/test-crowd-names.mjs +205 -0
  344. package/kits/hub-game/scripts/test-decor-client.mjs +344 -0
  345. package/kits/hub-game/scripts/test-decor.mjs +464 -0
  346. package/kits/hub-game/scripts/test-default-environment-root.mjs +95 -0
  347. package/kits/hub-game/scripts/test-default-environment.mjs +267 -0
  348. package/kits/hub-game/scripts/test-door-analytics.mjs +58 -0
  349. package/kits/hub-game/scripts/test-door-jump.mjs +100 -0
  350. package/kits/hub-game/scripts/test-earned-client.mjs +459 -0
  351. package/kits/hub-game/scripts/test-earned.mjs +1224 -0
  352. package/kits/hub-game/scripts/test-emote-bubble.mjs +110 -0
  353. package/kits/hub-game/scripts/test-far-avatars.mjs +340 -0
  354. package/kits/hub-game/scripts/test-fps-telemetry.mjs +112 -0
  355. package/kits/hub-game/scripts/test-frame-batch.mjs +252 -0
  356. package/kits/hub-game/scripts/test-fresh-friends.mjs +118 -0
  357. package/kits/hub-game/scripts/test-friend-bests.mjs +435 -0
  358. package/kits/hub-game/scripts/test-grab-orbit.mjs +961 -0
  359. package/kits/hub-game/scripts/test-grab.mjs +7 -0
  360. package/kits/hub-game/scripts/test-hats.mjs +422 -168
  361. package/kits/hub-game/scripts/test-high-only.mjs +170 -0
  362. package/kits/hub-game/scripts/test-hub-leaving.mjs +203 -0
  363. package/kits/hub-game/scripts/test-hub-ops.mjs +758 -2
  364. package/kits/hub-game/scripts/test-hub-trip.mjs +1594 -12
  365. package/kits/hub-game/scripts/test-hud-clear.mjs +484 -57
  366. package/kits/hub-game/scripts/test-hud-defects-dom.mjs +100 -0
  367. package/kits/hub-game/scripts/test-hud-rate.mjs +224 -0
  368. package/kits/hub-game/scripts/test-hud-safe-visibility-dom.mjs +83 -0
  369. package/kits/hub-game/scripts/test-idle.mjs +427 -1
  370. package/kits/hub-game/scripts/test-interest-cap.mjs +36 -0
  371. package/kits/hub-game/scripts/test-interest-cells.mjs +513 -0
  372. package/kits/hub-game/scripts/test-interest-client.mjs +118 -0
  373. package/kits/hub-game/scripts/test-interest.mjs +15 -0
  374. package/kits/hub-game/scripts/test-invites-client.mjs +430 -0
  375. package/kits/hub-game/scripts/test-invites.mjs +109 -0
  376. package/kits/hub-game/scripts/test-keys.mjs +46 -1
  377. package/kits/hub-game/scripts/test-labels.mjs +664 -0
  378. package/kits/hub-game/scripts/test-landscape-layout.mjs +194 -0
  379. package/kits/hub-game/scripts/test-list-scroll-dom.mjs +49 -0
  380. package/kits/hub-game/scripts/test-load-abandon.mjs +246 -0
  381. package/kits/hub-game/scripts/test-loading-cover.mjs +162 -0
  382. package/kits/hub-game/scripts/test-manifest.mjs +472 -0
  383. package/kits/hub-game/scripts/test-menu-client.mjs +585 -0
  384. package/kits/hub-game/scripts/test-menu.mjs +319 -0
  385. package/kits/hub-game/scripts/test-npcs.mjs +2528 -13
  386. package/kits/hub-game/scripts/test-object-entry.mjs +76 -0
  387. package/kits/hub-game/scripts/test-observed.mjs +745 -0
  388. package/kits/hub-game/scripts/test-pack.mjs +7 -0
  389. package/kits/hub-game/scripts/test-pad-cues.mjs +304 -0
  390. package/kits/hub-game/scripts/test-pad-occupancy.mjs +177 -0
  391. package/kits/hub-game/scripts/test-picker.mjs +541 -0
  392. package/kits/hub-game/scripts/test-placement-cache.mjs +690 -0
  393. package/kits/hub-game/scripts/test-progress-reset.mjs +559 -0
  394. package/kits/hub-game/scripts/test-push-visit.mjs +26 -0
  395. package/kits/hub-game/scripts/test-quality.mjs +385 -0
  396. package/kits/hub-game/scripts/test-rehello.mjs +1733 -0
  397. package/kits/hub-game/scripts/test-relations-among.mjs +222 -0
  398. package/kits/hub-game/scripts/test-relations-refresh.mjs +188 -0
  399. package/kits/hub-game/scripts/test-resume-action-order.mjs +598 -0
  400. package/kits/hub-game/scripts/test-resume-held.mjs +239 -0
  401. package/kits/hub-game/scripts/test-resume-pose.mjs +142 -0
  402. package/kits/hub-game/scripts/test-safe-events-dom.mjs +116 -0
  403. package/kits/hub-game/scripts/test-safe-layout.mjs +330 -0
  404. package/kits/hub-game/scripts/test-say.mjs +1 -1
  405. package/kits/hub-game/scripts/test-shot.mjs +901 -0
  406. package/kits/hub-game/scripts/test-signin-client.mjs +45 -0
  407. package/kits/hub-game/scripts/test-soundscape.mjs +5437 -0
  408. package/kits/hub-game/scripts/test-spin.mjs +314 -0
  409. package/kits/hub-game/scripts/test-standing.mjs +449 -0
  410. package/kits/hub-game/scripts/test-storage-limit.mjs +333 -0
  411. package/kits/hub-game/scripts/test-stuck.mjs +1904 -0
  412. package/kits/hub-game/scripts/test-talk-overlay-dom.mjs +130 -0
  413. package/kits/hub-game/scripts/test-tier-cells.mjs +706 -0
  414. package/kits/hub-game/scripts/test-tiers-render.mjs +412 -0
  415. package/kits/hub-game/scripts/test-tiers.mjs +476 -2
  416. package/kits/hub-game/scripts/test-toast-band.mjs +61 -0
  417. package/kits/hub-game/scripts/test-try-on.mjs +22 -22
  418. package/kits/hub-game/scripts/test-vis.mjs +770 -0
  419. package/kits/hub-game/scripts/test-visibility.mjs +134 -0
  420. package/kits/hub-game/scripts/test-weakest-tier.mjs +924 -0
  421. package/kits/hub-game/scripts/test-world-labels.mjs +367 -0
  422. package/kits/hub-game/scripts/test-yours-chrome.mjs +210 -0
  423. package/kits/hub-game/scripts/test-yours.mjs +403 -0
  424. package/kits/multiplayer-3d/CLAUDE.md +50 -0
  425. package/kits/multiplayer-3d/castle.json +5 -5
  426. package/kits/multiplayer-3d/code/client/avatars.js +7 -0
  427. package/kits/multiplayer-3d/code/client/gait.js +65 -0
  428. package/kits/multiplayer-3d/code/client/joinFailure.js +27 -0
  429. package/kits/multiplayer-3d/code/client/nameTags.js +59 -4
  430. package/kits/multiplayer-3d/code/client/resumeGate.js +139 -0
  431. package/kits/multiplayer-3d/code/options.js +5 -0
  432. package/kits/multiplayer-3d/code/server/ownership.js +10 -2
  433. package/kits/multiplayer-3d/code/server/sceneBodies.js +12 -0
  434. package/kits/multiplayer-3d/code/server/world.js +7 -0
  435. package/kits/multiplayer-3d/code/systems/multiplayer.js +443 -34
  436. package/kits/multiplayer-3d/package-lock.json +8 -1
  437. package/kits/multiplayer-3d/package.json +3 -1
  438. package/kits/multiplayer-3d/scripts/fixtures/README.md +11 -0
  439. package/kits/multiplayer-3d/scripts/fixtures/ownership-legacy.json +2 -0
  440. package/kits/multiplayer-3d/scripts/ownership-harness.mjs +102 -0
  441. package/kits/multiplayer-3d/scripts/ownership-loader.mjs +46 -0
  442. package/kits/multiplayer-3d/scripts/ownership-worker.mjs +15 -0
  443. package/kits/multiplayer-3d/scripts/record-ownership-session.mjs +98 -0
  444. package/kits/multiplayer-3d/scripts/test-eligible-claims.mjs +167 -0
  445. package/kits/multiplayer-3d/scripts/test-join-watchdog.mjs +436 -0
  446. package/kits/multiplayer-3d/scripts/test-own-name-tag.mjs +247 -0
  447. package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +624 -0
  448. package/kits/physics-2d/CLAUDE.md +19 -1
  449. package/kits/physics-2d/castle.json +2 -2
  450. package/kits/physics-2d/engine/frozenActors.js +233 -0
  451. package/kits/physics-2d/engine/scene.js +337 -3
  452. package/kits/physics-2d/engine/skyKey.js +129 -0
  453. package/kits/physics-2d/engine/stillClock.js +106 -0
  454. package/kits/physics-2d/engine/updateBudget.js +21 -0
  455. package/kits/physics-2d/eslint.config.js +1 -1
  456. package/kits/physics-2d/play/behaviors/AnalogStick.js +198 -0
  457. package/kits/physics-2d/play/behaviors/Camera.js +40 -0
  458. package/kits/physics-2d/play/behaviors/Collider.js +122 -0
  459. package/kits/physics-2d/play/behaviors/Draggable.js +115 -0
  460. package/kits/physics-2d/play/behaviors/Goal.js +46 -0
  461. package/kits/physics-2d/play/behaviors/Joints.js +126 -0
  462. package/kits/physics-2d/play/behaviors/Layout.js +71 -0
  463. package/kits/physics-2d/play/behaviors/RigidBody.js +57 -0
  464. package/kits/physics-2d/play/behaviors/Slingshot.js +142 -0
  465. package/kits/physics-2d/play/behaviors/SoundPlayer.js +263 -0
  466. package/kits/physics-2d/play/behaviors/Sprite.js +406 -0
  467. package/kits/physics-2d/play/behaviors/Style.js +209 -0
  468. package/kits/physics-2d/play/behaviors/Text.js +85 -0
  469. package/kits/physics-2d/play/behaviors/Video.js +93 -0
  470. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +326 -1
  471. package/kits/physics-3d/CLAUDE.md +42 -529
  472. package/kits/physics-3d/behaviors/Body.jsx +3 -0
  473. package/kits/physics-3d/behaviors/Model.jsx +3 -0
  474. package/kits/physics-3d/behaviors/Player.jsx +661 -87
  475. package/kits/physics-3d/behaviors/Shape.jsx +3 -0
  476. package/kits/physics-3d/behaviors/Solid.jsx +3 -0
  477. package/kits/physics-3d/behaviors/Transform.jsx +3 -0
  478. package/kits/physics-3d/castle.json +3 -3
  479. package/kits/physics-3d/docs/engine-camera.md +542 -0
  480. package/kits/physics-3d/docs/engine-frame-cap.md +136 -0
  481. package/kits/physics-3d/docs/engine-load.md +149 -0
  482. package/kits/physics-3d/docs/engine-look.md +114 -0
  483. package/kits/physics-3d/docs/engine-shadows.md +372 -0
  484. package/kits/physics-3d/docs/engine-skip-work.md +187 -0
  485. package/kits/physics-3d/docs/engine-sky.md +198 -0
  486. package/kits/physics-3d/docs/engine-static-actors.md +226 -0
  487. package/kits/physics-3d/docs/engine-view.md +37 -0
  488. package/kits/physics-3d/docs/pxmodel-format.md +9 -1
  489. package/kits/physics-3d/engine3d/PlayOnly3D.jsx +5 -1
  490. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +19 -277
  491. package/kits/physics-3d/engine3d/actornode.js +87 -0
  492. package/kits/physics-3d/engine3d/animationBudget.js +23 -0
  493. package/kits/physics-3d/engine3d/branches.js +3 -13
  494. package/kits/physics-3d/engine3d/cage.js +2 -7
  495. package/kits/physics-3d/engine3d/cageops.js +2 -17
  496. package/kits/physics-3d/engine3d/dataBehaviors.js +12 -0
  497. package/kits/physics-3d/engine3d/editorWorld.js +6 -0
  498. package/kits/physics-3d/engine3d/emptynodes.js +232 -0
  499. package/kits/physics-3d/engine3d/framecap.js +99 -0
  500. package/kits/physics-3d/engine3d/frozenphysics.js +140 -0
  501. package/kits/physics-3d/engine3d/frozenstatics.js +273 -0
  502. package/kits/physics-3d/engine3d/gait.js +126 -0
  503. package/kits/physics-3d/engine3d/initialModelFiles.js +18 -0
  504. package/kits/physics-3d/engine3d/kithooks.js +47 -0
  505. package/kits/physics-3d/engine3d/look.js +514 -48
  506. package/kits/physics-3d/engine3d/lookbake.js +208 -0
  507. package/kits/physics-3d/engine3d/materialpresets.js +2 -0
  508. package/kits/physics-3d/engine3d/modelFiles.js +3 -17
  509. package/kits/physics-3d/engine3d/modelMath.js +49 -0
  510. package/kits/physics-3d/engine3d/modelready.js +16 -0
  511. package/kits/physics-3d/engine3d/motion.js +39 -10
  512. package/kits/physics-3d/engine3d/nearshadows.js +106 -21
  513. package/kits/physics-3d/engine3d/optimize.js +9 -5
  514. package/kits/physics-3d/engine3d/orbitinput.js +522 -10
  515. package/kits/physics-3d/engine3d/orbitlens.js +48 -0
  516. package/kits/physics-3d/engine3d/ownmodel.js +213 -0
  517. package/kits/physics-3d/engine3d/partgeometry.js +1 -16
  518. package/kits/physics-3d/engine3d/paths.js +1 -9
  519. package/kits/physics-3d/engine3d/playTimings.js +50 -0
  520. package/kits/physics-3d/engine3d/playerRun.js +372 -0
  521. package/kits/physics-3d/engine3d/pxmodel.js +42 -11
  522. package/kits/physics-3d/engine3d/rapier.js +27 -0
  523. package/kits/physics-3d/engine3d/scatter.js +1 -11
  524. package/kits/physics-3d/engine3d/shadowfade.js +890 -0
  525. package/kits/physics-3d/engine3d/sky.js +547 -0
  526. package/kits/physics-3d/engine3d/skylife.js +306 -0
  527. package/kits/physics-3d/engine3d/squarefirst.js +177 -0
  528. package/kits/physics-3d/engine3d/stillshadows.js +399 -0
  529. package/kits/physics-3d/engine3d/sweep.js +1 -25
  530. package/kits/physics-3d/engine3d/unchanged.js +11 -0
  531. package/kits/physics-3d/engine3d/viewrange.js +52 -0
  532. package/kits/physics-3d/engine3d/world3d.js +1253 -76
  533. package/kits/physics-3d/eslint.config.js +2 -1
  534. package/kits/physics-3d/main.jsx +10 -2
  535. package/kits/physics-3d/package-lock.json +7 -0
  536. package/kits/physics-3d/package.json +5 -1
  537. package/kits/physics-3d/play/behaviors/Body.js +31 -0
  538. package/kits/physics-3d/play/behaviors/Door.js +37 -0
  539. package/kits/physics-3d/play/behaviors/Lookable.js +16 -0
  540. package/kits/physics-3d/play/behaviors/Model.js +23 -0
  541. package/kits/physics-3d/play/behaviors/Pickup.js +46 -0
  542. package/kits/physics-3d/play/behaviors/Player.js +1204 -0
  543. package/kits/physics-3d/play/behaviors/Shape.js +47 -0
  544. package/kits/physics-3d/play/behaviors/Solid.js +16 -0
  545. package/kits/physics-3d/play/behaviors/Transform.js +29 -0
  546. package/kits/physics-3d/pnpm-lock.yaml +8 -0
  547. package/kits/physics-3d/scripts/bench-shadow-fade.mjs +37 -0
  548. package/kits/physics-3d/scripts/build-rapier-gz.mjs +56 -0
  549. package/kits/physics-3d/scripts/frozen-statics-fixture.mjs +141 -0
  550. package/kits/physics-3d/scripts/look-baseline.mjs +155 -0
  551. package/kits/physics-3d/scripts/test-camera-follow.mjs +5 -1
  552. package/kits/physics-3d/scripts/test-camera-orbit.mjs +2613 -82
  553. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +2 -2
  554. package/kits/physics-3d/scripts/test-empty-gait-hints.mjs +89 -0
  555. package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +438 -0
  556. package/kits/physics-3d/scripts/test-frame-cap.mjs +452 -0
  557. package/kits/physics-3d/scripts/test-frozen-nested.mjs +49 -0
  558. package/kits/physics-3d/scripts/test-frozen-statics-legacy-physics2d.mjs +123 -0
  559. package/kits/physics-3d/scripts/test-frozen-statics.mjs +434 -0
  560. package/kits/physics-3d/scripts/test-gait.mjs +387 -0
  561. package/kits/physics-3d/scripts/test-look-bake.mjs +1056 -0
  562. package/kits/physics-3d/scripts/test-model-parse-cache.mjs +92 -0
  563. package/kits/physics-3d/scripts/test-near-shadows.mjs +5 -2
  564. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +2001 -0
  565. package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +582 -0
  566. package/kits/physics-3d/scripts/test-orbit-shot.mjs +657 -0
  567. package/kits/physics-3d/scripts/test-orbit-view.mjs +230 -0
  568. package/kits/physics-3d/scripts/test-rapier-gz.mjs +106 -0
  569. package/kits/physics-3d/scripts/test-skip-empty-nodes.mjs +845 -0
  570. package/kits/physics-3d/scripts/test-sky.mjs +2470 -0
  571. package/kits/physics-3d/scripts/test-square-first.mjs +921 -0
  572. package/kits/physics-3d/scripts/test-static-actors.mjs +10 -1
  573. package/kits/physics-3d/scripts/test-static-physics.mjs +4 -1
  574. package/kits/physics-3d/scripts/test-static-scenery.mjs +2174 -0
  575. package/kits/physics-3d/scripts/test-steady-hover.mjs +7 -2
  576. package/kits/physics-3d/scripts/test-still-shadows.mjs +477 -0
  577. package/kits/physics-3d/scripts/test-view-range.mjs +260 -0
  578. package/kits/physics-3d/systems/physics3d.js +419 -9
  579. package/kits/real-time/castle.json +2 -2
  580. package/kits/real-time/code/client/connection.js +33 -10
  581. package/kits/real-time/code/client/gameHooks.js +2 -0
  582. package/kits/real-time/code/client/joinOverlay.js +9 -4
  583. package/kits/real-time/code/server/gameHooks.js +7 -0
  584. package/kits/real-time/code/server/session.js +102 -22
  585. package/kits/real-time/package-lock.json +1 -1
  586. package/package.json +2 -2
  587. package/dist/shell/assets/index-Cf61cNfT.css +0 -1
@@ -2,8 +2,9 @@
2
2
 
3
3
  A game behind a door in the Cauldron hub town. A hub game is a
4
4
  `castle.multiplayer-3d` deck that meets the **hub contract**
5
- (`docs/contract.md`, version 1): the kit draws every player as their platform
6
- avatar, brings them in at the arrival together and sends them back out
5
+ (`docs/contract.md`, latest version 1.136; manifest `hub.contract: 1`): the kit
6
+ draws every player as their platform avatar, brings them in at the arrival
7
+ together and sends them back out
7
8
  through the door they came in by, and draws the HUD, labels and Back control
8
9
  the game declares. The game itself is scene data plus server hooks -- **no
9
10
  client code** (Tier 0).
@@ -11,6 +12,15 @@ client code** (Tier 0).
11
12
  Read `docs/contract.md` before changing the `hub` block or the server hooks;
12
13
  it is what every published hub game depends on.
13
14
 
15
+ For a mind's chat, `npcAsks(hub, npc, playerId)` may return
16
+ `{ persistentAsks: string[] }` or null (v1.80, contract §13). The kit re-reads
17
+ it with the speaker's notes, keeping at most two distinct, trimmed questions
18
+ of at most 40 characters. Only that player's `hub-npc-notes` carries them;
19
+ they lead the three-chip refill row and may return after being sent while
20
+ the place keeps offering them. Null clears them. The hook is synchronous;
21
+ errors are caught and logged once without the hook's words. Without it,
22
+ notes messages and the client's refill behavior stay exactly as before.
23
+
14
24
  ## Quick reference
15
25
 
16
26
  <!-- Injected into Castle's create assistant every turn; keep this compact and factual. -->
@@ -26,8 +36,8 @@ it is what every published hub game depends on.
26
36
  get `hub`, the place's context: `ready(hub)`, `arrive(hub, group)`,
27
37
  `step(hub, dt)`, `leave(hub, playerId, { userId, username })` (a result may be
28
38
  reported there), `shutdown(hub)` (finish writing), `message(hub, player, data)`,
29
- `fall(hub, playerId)` (below the place's `fallY`; a scene with
30
- `"ground": { "none": true }` has no ground and catches at -20 by default).
39
+ `fall(hub, playerId)` (below the place's `fallY`; every place catches at
40
+ -20 by default, including past the edge of the finite implicit ground).
31
41
  `server.main` stays `imports/castle.hub-game/code/server/index.js`.
32
42
  - **A player's progress between visits** goes in `hub.session.storage.deck`
33
43
  under `'<name>:<userId>'`, never user scope, which their own client can
@@ -35,7 +45,7 @@ it is what every published hub game depends on.
35
45
  - What `hub` does: `players()`, `actorsWith(component)` (each with its `t`,
36
46
  `props`, `shape` and `body`), `now`, `placeAt`,
37
47
  `hold` / `release` (keep a player still), `setHud(spec, playerId?)`,
38
- `hide` / `show` (an actor, for everyone), `move(actorId, { x, y, z,
48
+ `hide` / `show` (an actor, for everyone or selected viewers), `move(actorId, { x, y, z,
39
49
  rotationY }, { overMs })` (a `Body` `"kinematic"` actor: platforms, sweepers,
40
50
  gates), `tint(actorId, '#rrggbb' | null)` (a Shape actor's colour),
41
51
  `mark(playerId, { text, color } | null)` (a coloured tag over a player's
@@ -43,11 +53,24 @@ it is what every published hub game depends on.
43
53
  (v1.4: `halo`, `aura`, `orbit` or a hat `hat-<id>`, the ids in
44
54
  `code/client/hats.js` `HATS`; in `#rrggbb`, rarity 0-9, worn on the
45
55
  player's avatar in every hub place once ghost keeps it),
56
+ `leaving(playerId, text)` (v1.52: a private line about next visit, trimmed
57
+ and cut at 120 characters, shown when leaving; `null` or empty clears it),
46
58
  `tryOn(playerId, { kind, color, rarity } | null)` (v1.28: the same wearable
47
59
  shown in this place only and never saved -- a shop's try-on, a costume for
48
60
  the visit; the one the player owns is untouched and is drawn again on
49
- `null`, when they leave or when the place ends), `spawn(fromActorId, at)` / `despawn(id)` (a
50
- copy of a scene actor, often a hidden prototype), `pose(actorId)` /
61
+ `null`, when they leave or when the place ends), `wearing(playerId)` (v1.41:
62
+ the wearable a player here owns, or null, to say what they have on),
63
+ `unlock(playerId, id)` (v1.53: an earned item the deck declares in
64
+ `hub.unlocks` -- up to 8 badge, pin, belt, sash or held items (`shape`),
65
+ plus up to 6 furniture or deed items and up to 16 pet items (`piece`, v1.70/v1.73), no rarity -- for a stated
66
+ deed; a promise of `{ isNew, earned, saved }` or null when refused; `saved` false
67
+ for a guest's or the dev serve's, kept for the session only), `earned(playerId)`
68
+ (the earned item a player shows, or null), `wearEarned` / `unlocksOf` (the
69
+ town's choice and read; contract §11: home items appear in `owned` but are
70
+ never worn, sent in `hubEarned` or shown in the wardrobe; a first home unlock
71
+ says "Sent to your house", or "Sent to your boat at the Harbour" for a `boat-`
72
+ piece (v1.77); piece ids are in `docs/home-pieces.md`), `spawn(fromActorId, at)` /
73
+ `despawn(id)` (a copy of a scene actor, often a hidden prototype), `pose(actorId)` /
51
74
  `reset(actorId, at?)` (read a body; put a loose object back, at rest),
52
75
  `tune(playerId, { speed,
53
76
  jump } | null)` (one player's own walk, as multipliers of the preset),
@@ -56,22 +79,157 @@ it is what every published hub game depends on.
56
79
  `result(playerId, { outcome, score, stats })`, `results(playerId)` (ghost's
57
80
  recent results and records of a player), `end(playerIds?)`,
58
81
  `go(door, playerIds)`, `send`, `broadcast`, `session`, `sim`, `place`.
82
+ - **Place menu** (v1.79): only with `menu: true`,
83
+ `hub.menu(playerId, { title, note?, readOnly?, face?, sections: [{ title, items:
84
+ [{ id, label, color?, icon?, on? }] }] } | null)` offers that player a
85
+ private bottom sheet. `menu(hub, playerId, id)` hears current version picks
86
+ or reserved `close`; the place closes with null. Icons are `EARNED_SHAPES`
87
+ or `HATS` ids; `close` cannot be an item id. Optional `face` (v1.85) holds
88
+ the local avatar's facing while this sheet is shown under orbit control
89
+ (including held orbit shots): finite degrees,
90
+ normalised into [-180, 180), looking along (sin f, cos f) in x/z.
91
+ Holds and seats take precedence. Follow-camera places ignore `face`;
92
+ camera yaw (`camAngle`) is never changed.
93
+ Optional `presentation: 'rows'` (v1.136) shows full-width text rows; items
94
+ may add `columns: [left, middle, right]` (each 1..24 code points) and
95
+ `readOnly`. Optional `footer: [{ id, label }]` pins up to four actions below
96
+ the scroll. Rows and footer share the existing 48-item budget and pick path.
97
+ Close, replacement without it, leave and higher-priority UI release it;
98
+ absent `face` preserves control and wire bytes. Bounds and validation: contract
99
+ §9; `scripts/test-menu.mjs` and `test-menu-client.mjs`. No absent-key API,
100
+ hook lookup, state, chrome or wire bytes.
101
+ - **Owner and decorating** (v1.67): `hub.owner` is the platform owner's user id
102
+ or null; `hub.house: { devOwner: "first" }` keeps the first dev arrival as
103
+ owner for the session. A place with `hub.decor: { grid: { origin, w, d,
104
+ cell }, layers }` gets private `hub.decor.button/open/close/update` and the
105
+ `decor(hub, playerId, op)` hook: the kit draws the grid, catalogue, ghosts
106
+ and touch/mouse controls; the deck checks ownership, stock, collisions and
107
+ saving, then applies spawn/move/despawn/tint and updates the catalogue.
108
+ Spawned seats work for guests in these places. Contract §10 Decorating;
109
+ `scripts/test-decor.mjs` and `test-decor-client.mjs`. Absent keys add no wire
110
+ state, chrome or preview resources.
111
+ - **Per-viewer visibility** (v1.62): `hub.hide/show(actorId, { to: [playerIds] })`
112
+ replaces shared visibility for those connected players; either with
113
+ `clear: true` restores the shared view. Works for baked Models. Unknown or
114
+ disconnected players are ignored; at most 256 actor overrides per player.
115
+ Private calls return true when taken; invalid actor/options or exceeding the
116
+ cap warn once and return false without changes. Leaving drops overrides.
117
+ A result place with `resume: { keep: true }` may also set
118
+ `resumeVisibility: true`: for the retained visit's <60 s absence, keep the
119
+ authenticated viewer's overrides. This requires an exported `resume` hook;
120
+ on return the kit holds stale replay, runs that hook early, then sends the
121
+ current whole map. Rebuild every current mask synchronously before the hook
122
+ returns or first awaits. Changed/missing identity, travel, expiry, shutdown
123
+ and forget delete the cache; offline targets are still ignored. This is
124
+ server-only and adds no public place/wire field. WORLD can precede hello and
125
+ replay, so a cleared client, or an actor newly made private while offline, can
126
+ briefly have the shared view. The guarantee starts at the first replayed
127
+ merged state; async-late mask writes and a failing hook are not covered.
128
+ Client drawing, pads, idle and soundscape use the merged visibility; server
129
+ bodies and shared visibility logic (pads, labels, doors, idle) stay unchanged.
130
+ Shared-only places send exactly the same snapshots, deltas and messages.
131
+ - **Moment shots** (v1.61): `hub.shot(playerId, { look: { x, y, z }, distance,
132
+ pitch, yaw })` privately blends and holds the orbit camera; `null` clears.
133
+ Finite values, distance > 0 m, angles in degrees, pitch capped at ±89. The
134
+ place scene must use `cameraControl: "orbit"`; the shot is not collided.
135
+ Four changed shots/s (burst four), equal poses suppressed for 1 s; clears
136
+ bypass the budget. True when sent, false and warn once otherwise; invalid
137
+ poses warn once and clear. The client clears on travel, leave, scene
138
+ load/place change and disconnect, preserving shots assigned by deck code.
139
+ The server renews a held pose every 2 s and immediately on a fresh join,
140
+ without spending the rate budget. Equal renewals keep the same shot object.
141
+ Renewals restore a shot lost to a disconnect, but never re-create one dropped
142
+ for a scene load, travel, round end or a deck's own `orbitShot`; only a fresh
143
+ `hub.shot` call does that. Travel and round end stop server renewals.
144
+ The client drops a shot not renewed for 5 s, on its first watcher run even
145
+ after a background-tab pause, so it cannot outlive its server or connection.
146
+ No client code or manifest key needed.
147
+ A fixed-view scene may opt into `engine.camera.arrivalFromShot: true`:
148
+ on fresh hub arrival, its persistent movement angle is seeded from the
149
+ accepted orbit shot yaw, including a shot delivered after the arrival.
150
+ Later shot changes and lease renewals do not reseed it. Absent or false,
151
+ the arrival facing seeds the angle as before; Player's shot behavior is
152
+ unchanged. This scene key needs no hub contract version or wire field.
153
+ Use `engine.camera.arrivalFromShot: { "yaw": -38 }` when a temporary
154
+ portrait can arrive first: seed only after an accepted shot matches that
155
+ heading (modulo 360 degrees), including after the portrait closes.
156
+ `engine.camera.walkFromShot: true` makes keyboard and stick walking use
157
+ a valid held shot's drawn yaw (including its blend; target yaw before its
158
+ first placement), keeping up on screen even if the arrival heading drifts.
159
+ It does not change persistent camAngle. Absent/false or no valid shot keeps
160
+ the existing walking basis; `arrivalFromShot` still seeds the follow heading.
161
+ - **The choice card** (v1.68): `"ballot": { "lines": [{ "id", "text", "about":
162
+ "face" | "self" }] }` in a place's hub block (or `true`: faces and options
163
+ only; ≤ 32 lines, ids `[a-z0-9-]{1,24}`, text ≤ 40). `hub.ballot(playerIds |
164
+ null, { title, text, until, mode: 'talk'|'vote'|'reveal', faces: [{ playerId,
165
+ note, off, votes, mark }], options: [{ id, text }], lines, feed: [{ from, to,
166
+ line }], picked } | null)` shows a phone bottom sheet of faces and chips
167
+ (per-player replaces shared; `null` for everyone clears all). Taps reach the
168
+ hook `ballot(hub, playerId, { face, line, option, mode })` as ids only,
169
+ checked against that player's card, three then one per 1.5 s. **No free
170
+ text**: never put a player's words in title/text/note/options; feed lines
171
+ are worded by the client from ids. The place keeps the feed and counts votes
172
+ (`picked` locks a vote in at once). Rule A: a card's version `v` moves only
173
+ when what can be tapped changes (mode, faces/off, lines, option ids,
174
+ picked), not on feed/text refreshes; a tap carries it and counts only on
175
+ the delivered, current version.
176
+ The card is drawn from who is here now: absent players' faces and feed rows
177
+ go, blocks among players here drop theirs and redact present names. Rule B:
178
+ without the key no ballot code runs, client or server (no `hub.ballot`).
179
+ - **Turning displays** (v1.55): `"HubSpin": { "rate": 45 }` (deg/s, ±720) on a
180
+ non-solid scene actor with no moving Body turns it on every client; no op.
181
+ - **Safe chrome** (v1.123): optional deck-only `hub.safeInsets: true` keeps
182
+ chrome inside CSS safe-area edges and outside both host-owned 64 × 56 top
183
+ corners. Oversize text wraps and cards scroll. Client-only; no wire field.
184
+ `window.castleHub.layout()` reports visible boxes for layout QA (§9).
59
185
  - **The HUD** is `{ title, big, text, timer: { since | until } }` in simulation
60
186
  ms (`hub.now`), drawn by the hub. It is the only way the game puts words on
61
187
  screen.
188
+ - **Reachable action overflow** is a scene choice: set
189
+ `"engine": { "hubActionOverflow": true }` in a scene that may receive three
190
+ `hub.actions` offers. The kit measures one row, then at most two rows; where
191
+ neither clears the scene's visible controls and touch regions it keeps every
192
+ offer behind a keyboard-accessible More/Actions sheet. The sheet dismisses
193
+ with Close, Escape or platform Back and holds only local input while open.
194
+ Without the scene key, action chips use the legacy stack unchanged.
62
195
  - **Results** are server-only, once per player per visit, checked against
63
196
  `hub.result` in `castle.json`. No free text: the town writes the words. The
64
197
  `outcome` may be left out when a `score` says it all (a time trial).
198
+ - **A phone back within the reconnect window** (an app switch) is not arrived
199
+ again in a game unless the place sets `"resume": true` (v1.72): then `leave`
200
+ then `arrive` run again for the same player id, so the game must restore
201
+ that player's round state by account. One result per visit (a result
202
+ reported in `leave` is kept), one deadline, the end and first door kept.
203
+ - **Pose-only reconnect** (v1.117): `resumeArrivalPose: true` keeps only pose
204
+ and facing for a same-id, same signed-in account return within 60 seconds.
205
+ Ordinary `leave` and `arrive` still run; pose is restored after `arrive`.
206
+ Result places also need `resume: true`. Retained-visit modes conflict.
207
+ Anonymous/new identities, travel, end, expiry and shutdown restore nothing.
208
+ This adds no public manifest/wire field; absent keeps existing behavior.
65
209
  - **Players arrive at `hub.arrival.actor`**, in a row, facing
66
210
  `hub.arrival.face`, already placed when `arrive` runs. Never move the Player
67
211
  actor in the scene to change that -- change the arrival.
212
+ - **Every §5 ask-slot card expires** (v1.125) 12 s after first display, or
213
+ sooner at 3 m of movement or on entering any pad. This is universal
214
+ client lifecycle, not a manifest opt-in: it covers invitations, proposals,
215
+ play/follow, Play again and Your games without new wire bytes. Reconnect
216
+ replay does not resurrect an expired observable card. Server withdrawal can
217
+ end a party offer sooner, and identical same-sender invitation packets count
218
+ as one offer until a received clear or identity change; leaving toast is unchanged.
68
219
  - **Exit is always the hub's**: the Back control, `hub.end`, or
69
220
  `hub.maxDurationSec`. A game has no lobby and no leave button.
70
221
  - Never ship `blueprints/other-player.scene` or restyle the Player: every
71
- player is drawn as their avatar (`blueprints/avatar-<n>.scene` here).
222
+ player is drawn as their avatar (`blueprints/avatar-<n>.scene` here, sixteen
223
+ of them).
72
224
  - Controller: `"walk"` (the engine's `Player`) is the only preset; `hub.tune`
73
225
  scales one player's speed and jump within it. No
74
226
  player shove: other players are kinematic.
227
+ - A scene without a top-level `background`, `engine.sky` or `engine.view`
228
+ gets the hub's cheap pale-sky clear and linear ground fog. Authored
229
+ environment keys remain the whole picture on every graphics tier. Root
230
+ `hub.defaultEnvironment: false` disables that fallback and the canvas fall
231
+ fade for every local or mounted scene; it does not disable server fall
232
+ catching or a scene's authored environment.
75
233
  - **Grab and throw** (contract v1.3): `"grab": true` in the `hub` block (or
76
234
  `{ throwSpeed, holdDistance, holdHeight }`) gives players a Grab / Throw
77
235
  button for the place's `Body` `"dynamic"` actors (crates, barrels). The
@@ -83,13 +241,47 @@ it is what every published hub game depends on.
83
241
  the button up through a moment at the reach, the cone or a shared owner --
84
242
  for places played on phones. `keepHeld: true` (contract v1.25) keeps a
85
243
  held object its holder's when another player stands nearer; without it the
86
- nearer player is handed it and the hold ends.
244
+ nearer player is handed it and the hold ends. In a scene with the engine's
245
+ orbit camera key (`"engine": { "camera": { "follow": "rigid", "control":
246
+ "orbit" } }`) a throw goes where the camera looks (PI - camAngle), not where
247
+ the character faces: the press turns the character that way
248
+ (`scene.faceRequest`), swings the held object round to the hold point along
249
+ it, and lets go once a movement report with the new facing has gone out
250
+ (150 ms at most without one; 2 s at most in all), so the server's
251
+ `hub.sim` facing is the throw's. The swing never puts the object more than
252
+ 0.5 m (straight line) from any position reported since the newest report
253
+ the server's body is sure to have reached (each as the report carried it:
254
+ the body where the hub left it, which the multiplayer kit packs straight
255
+ after, not the body a frame later once the client's physics, which runs
256
+ before the hub, has moved it on) -- acknowledged by multiplayer-3d
257
+ in a broadcast whose simulation time is past the ack's `tAck`, so a step ran
258
+ after it -- carry reports from before the press included. So neither
259
+ reports bunched by the network nor ticks that run no physics step can break
260
+ the owned-object move bound and take the object away mid-throw; half a turn
261
+ takes about a second on a good connection, and a swing the server cannot
262
+ confirm stalls and throws at the 2 s give-up from where it got. The default
263
+ (keyless) carry has no such bound: at the carry speed two of its reports
264
+ bunched into one tick can exceed the 0.6 m and lose the object (card
265
+ hub-game-grab-the-pickup-ease-in-1-2-m-3-m-hold). The swing adds no exposure
266
+ of its own: the carry before the press is that same carry, and the swing
267
+ never moves the object anywhere a report could fail (one the carry already
268
+ sent too far stalls it, and only a contact push in the client's physics,
269
+ which the carry shares, could move it further). The grab offer and the carry still follow
270
+ the character's facing. Without the key a throw is exactly what it was
271
+ (scripts/test-grab-orbit.mjs holds both).
87
272
  `hub.keepFor(actorId, playerId | null)` (contract v1.27) keeps a loose
88
273
  object for one player (a pillow of their own): nobody else is offered it or
89
274
  may grab it, and the `grab` hook is not asked about their tries. It ends
90
275
  with `null`, `hub.hide` and the player's leaving, and outlives `hub.reset`.
91
276
  It does not change who simulates the object, so its keeper is offered it
92
277
  only while nearest to it: put it beside them (`hub.reset(actorId, at)`).
278
+ - **Labels kept near** (contract v1.43): `"labels": "near"` in the `hub`
279
+ block, the deck's and the client's alone (like `tiers`). In a town the world
280
+ labels (`hub.label`'s plates, NPC lines and signs) are then kept near and
281
+ apart: a `"sign"` only within 12 m of the player (kept to 14 m), no two
282
+ overlapping, three at most (`code/client/labelsNear.js`, pure;
283
+ `scripts/test-labels.mjs`). Pointers, bubbles, emotes, marks and name tags
284
+ are not world labels. Without the key the hub system never calls it.
93
285
  - **A clear HUD** (contract v1.26): `"hud": { "clear": true }` in the `hub`
94
286
  block, for places played on phones. A big line with a text line under it
95
287
  is drawn at 32 px on one line (alone it keeps 56 px), labels, speech, marks
@@ -99,13 +291,148 @@ it is what every published hub game depends on.
99
291
  - **Idle play** (contract v1.6): `"idle": true` in the `hub` block (or
100
292
  `{ emotes, seats, sounds: ["sounds/x.mp3"] }`) gives players an emote picker
101
293
  (wave, dance, cheer, bow, spin, drawn on their avatar) and Sit on scene
102
- actors carrying `HubSeat` (`{ face, height }`); a seat is a hold, so the
294
+ actors carrying `HubSeat` (`{ face, height, pose }`, all optional; v1.82 `pose: "lie"` offers Lie down and draws a back-lying player, absent/`"sit"` keeps Sit); a seat is a hold, so the
103
295
  place's `hub.release` stands a sitter. Hooks `emote(hub, playerId, id)` and
104
296
  `sit(hub, playerId, seatId)` may refuse with `false`; `hub.emote(playerId,
105
297
  id)`, `hub.seat(playerId)`, and `hub.sound(actorId, file, { loop, volume,
106
298
  radius })` / `hub.sound(actorId, null)` for a listed sound file of the deck
107
299
  (carried in its content pack's `audio`, so a game behind a door sounds too;
108
300
  silent only on a town whose engine predates that).
301
+ - **The soundscape** (contract v1.42, v1.49, v1.50, v1.56, v1.60): `"soundscape": true` in the `hub`
302
+ block (or `{ babble, steps }`, each on unless `false`; the deck's, not a
303
+ place's) has the kit make its own sounds, synthesised in the client and
304
+ never a file or speech: NPC lines voiced as babble in each NPC's own voice
305
+ (from its actor id and name, or `HubNpc.voice: { type, pitch, rate, timbre }`),
306
+ footsteps under the player and those near them, and a speaker button (mute,
307
+ volume) that also sets the level of the place's `hub.sound` files. Client
308
+ only except explicit v1.50 `hub.cue` messages; without the key nothing of it
309
+ is made.
310
+ NPC babble uses all four original round-6 audition options, exported as
311
+ `VOICE_TYPES`: `townsfolk` (everyday, Rosenberg pulse, rate 3.3), `lively`
312
+ (excitable, same pulse, rate 4.6), `gruff` (older, LF Rd 1.2, rate 3.3,
313
+ formant gains [11,12,9,6]) and `gentle` (caring, Rosenberg, rate 3.3,
314
+ those lower formant gains, jitter 0.7/breath 0.75, jitter low-pass 120 Hz).
315
+ All use pitch 240, mouth 1.08, pace 1.3, breath low-pass 2400 Hz; source
316
+ gains 0.86/0.86/1.158/1.047 match the audition's voice RMS within 0.1%.
317
+ Valid `HubNpc.voice.type` wins; otherwise lower-case `${role} ${character}
318
+ ${name}` matches whole words in this fixed precedence (invalid types fall back):
319
+ - `gruff`: harbourmaster, harbour master, innkeeper, inn, fisher, captain,
320
+ smith, guard, elder, grandpa, old.
321
+ - `gentle`: nursery, clinic, nurse, nana, granny, gardener, healer, vet,
322
+ teacher, carer.
323
+ - `lively`: kid, child, barker, crier, hawker, postie, courier, runner,
324
+ coach, announcer, busker.
325
+ - Otherwise `townsfolk`; Innes does not match inn. Role is the place's own
326
+ key, character its characterBundle id, name its HubNpc name.
327
+ The actor/name hash keeps word seeds and per-NPC pitch
328
+ `240*2^(u*0.9-0.4)` (about 182–339 Hz), mouth rising with pitch (1–1.16),
329
+ and type rate ×0.9–1.1, with the same draws as before. Legacy
330
+ `HubNpc.voice.pitch` clamps to 80–500 Hz; `rate` clamps to 4–10 then maps
331
+ linearly to 2.5–6 (`7` → `4.25`); waveform `timbre` is accepted and ignored.
332
+ Complete words fit within 3 s including fade and 30 syllables. Each line
333
+ uses 22 synthesis nodes plus its distance gain, with per-context WeakMap
334
+ source/gate waves and noise. Breath puffs on the glottal open phase before
335
+ the formants; all three sources cut within 30 ms and every node releases
336
+ at natural end/failure. Scheduling origin is taken after construction.
337
+ `BABBLE_LEVEL` (~0.248) matches the old babble's median active RMS
338
+ (about −25.6 dBFS at volume 0.7), measured offline in Chromium.
339
+ Keyless/`babble: false` traces and market round-3 voices retain their
340
+ existing paths.
341
+ New fields alone opt into ambience and mapped steps: `zones` names a
342
+ bounds component (`x0,z0,x1,z1`); `ambience: { beds, default, spots, music }`
343
+ maps actor ids to `square`, `meadow`, `night`, `harbour`, `crowd` or `market`,
344
+ and spot component names to beds (nearest only, 4–14 m). The local player's
345
+ zone enters at the edge and stays until 0.75 m outside. Beds cross-fade
346
+ over 1.5 s, two at most plus one spot, sharing noise buffers; optional
347
+ quiet music uses fixed reusable voice pools per zone bed. Audible `hub.sound`
348
+ loops duck music to zero and ambience to 35%. Stadium, market (including
349
+ spots) and harbour beds render offline once per page context from the same
350
+ seeded generators into seamless 40/60/48 s loops, so phones play one buffer
351
+ instead of the live graph; music stays live. The original live generators
352
+ are the fallback when offline rendering is unavailable or fails. Referenced
353
+ heavy beds prewarm one at a time after activation while sound is allowed,
354
+ current zone first, with the same seeded plan scheduled up front and zero
355
+ offline suspends (v1.56). Object
356
+ `steps: { default, zones, paths }` maps surfaces (`street`, `grass`, `wood`,
357
+ `stone`, `sand`, `cobble`); path components carry `half`, `surface` and
358
+ `points` as `[x,z]` or `{x,z}`, and paths win over zones. Boolean steps
359
+ stay street everywhere; `true` creates no ambience, UI or action cues. Explicit `ui: true`
360
+ adds door departure (120 ms), settled arrival (320 ms), private town HUD
361
+ timer activity (180 ms) and chip tap (65 ms) cues on the UI bus. Two UI
362
+ voices and four starts per rolling second at most, two nodes per cue or
363
+ three for the whoosh, all released at the end; idle frames allocate none.
364
+ Only the departure tail may finish into a trip, without changing its
365
+ timing; hidden tab, mute or volume zero cuts even it. Arrival waits for
366
+ the first settled frame, at most 3 s. All other cues are dropped while
367
+ blocked. The first frame's private timer state is a baseline; shared/game
368
+ clocks and quiet changes make no activity cue. Holds do not distinguish
369
+ activities and token balances are only HUD text, so neither is parsed for
370
+ cues. No wire data is added. The hub passes chrome's optional `onChip`
371
+ callback only with UI enabled. All new sounds obey the first gesture,
372
+ two-frame settling gate and master volume. Validate with
373
+ `scripts/test-soundscape.mjs` and `test-manifest.mjs`.
374
+ v1.50 `cues: true` opts into `hub.cue({ player }, name)` or
375
+ `hub.cue({ actor, radius? }, name)` (default 12 m, 1–60): private delivery
376
+ or a distance-scaled broadcast, a six-token server budget per player or
377
+ shared for actors, false and warn once for invalid/off/rate-limited calls.
378
+ Closed names: kick, goal, cast, nibble, bite, catch, token, hat-bought,
379
+ hat-on, lantern, stamp, trial-start, trial-gate, trial-finish, pad-tick,
380
+ pad-go, court-chime, court-bell, court-splash, court-flutter, busker-jig,
381
+ busker-waltz. Court voices
382
+ are chime A at fixed stone 0, bell A (full 2.6 s), splash A and flutter B.
383
+ Chosen voices: kick A, catch C; other named audition voices as chosen.
384
+ Client state also voices wave B, dance C, cheer, bow, spin, sit
385
+ and private NPC panel opening; local full level, others within 12 m with
386
+ falloff and lower priority. Initial/quiet state is consumed silently.
387
+ Pads have only label text, so use explicit named cues, never text parsing.
388
+ Short cues and UI share two voices/four rolling starts per second on the UI bus;
389
+ the queue holds at most eight events, parts are built 75 ms ahead, and all
390
+ gates and cleanup apply. Cues alone adds no legacy UI callback or timer cue.
391
+ v1.60 busker names use `soundscapeBusker.js` on the UI bus, outside short
392
+ cue caps: actor sends every 10 s or less lease a loop for 25 s, within the
393
+ radius with linear falloff, actor present/not hidden and sound live. Only
394
+ the loudest loop plays; actor/name changes and departures fade in 0.3 s,
395
+ returning within the lease resumes. Private targets hear one full-gain pass.
396
+ Original 6/8 jig and 3/4 waltz phrases last 8–12 s with ten fixed nodes per
397
+ player, no per-note nodes, 0.3 s maximum lookahead and missed notes dropped.
398
+ Hide, scene change and teardown release all nodes; cues-off makes/drives no
399
+ busker layer. `BUSKER_LEVEL` targets −40 dBFS active RMS at volume 0.7,
400
+ pending Chromium calibration.
401
+ All six beds target about −33 dBFS active RMS at volume 0.7 (up 8 dB);
402
+ music is up 9 dB from its old −47 dBFS calibration target, sitting roughly
403
+ level with the beds, including stadium and the original market triangle tune.
404
+ Square A/B, Sunny A/B, Hollow warm/breathing pads, stadium Victory lap /
405
+ Arena bounce (126/132 BPM) and harbour Drift / Harbour jig (100 BPM waltz /
406
+ 76 dotted beats/min jig) alternate in seeded 3–5 minute runs ending on
407
+ bars, then 4–8 s silence. Hollow keeps its original D3 sine and a pad
408
+ 3 dB below it. Notes, timbres, envelopes and tempos are the auditions'.
409
+ Both song pools are made with the bed; frames create no music nodes.
410
+ Music nodes per song: square 37/42, sunny 37/27, Hollow pads 11/15 plus
411
+ two shared sine/envelope nodes, harbour 37/37, stadium 38/35.
412
+ Beds without/with music: square 7/87, meadow 7/72, night 7/36, harbour
413
+ 24/99, crowd 89/163, market 54/57; meadow/night may add a two-node call.
414
+ Harbour A-rolled has 22 generator nodes, including two 3.5 kHz wash
415
+ low-passes (Q 0) and 1.6 kHz foam high-passes; sea/gull/creak bypass the
416
+ wash roll-off. Both channels use identical gains. Random size stays
417
+ 0.6–1 for filter opening; body/foam amplitude uses
418
+ `0.6 + (size - 0.6) * 0.25` (0.6–0.7), without extra RNG draws.
419
+ `HARBOUR_WAVE_RMS` recalibrates the whole bed using a 300 s pure-JS
420
+ graph comparison to the previous bed. Whole-bed gain rises from
421
+ 0.316048 to 0.367716 (+1.315 dB), preserving model active RMS pending
422
+ a measured correction; the offline analysis is
423
+ `scripts/soundscape-wave-analysis.mjs` (called by the soundscape test).
424
+ Stadium crowd A keeps all 12 voices/eight clappers, 87 generator nodes.
425
+ Market Stalls A/Haggling B alternate in seeded 3–5 minute runs, draining
426
+ the last line before switching. Two 19-node Simlish pools retain pitches,
427
+ consonants, formants, pacing and envelopes; source phase continues between
428
+ lines. Three damped delays supply distance. Zone and spots share this
429
+ generator; a fallback spot adds 55 nodes at the existing 0.45 mix, no music.
430
+ All graphs, sources and delay loops release on fade/quiet/dispose; no
431
+ timers, real words or TTS. Stalled frames never replay missed lines.
432
+ Night's 4.1 kHz periodic cricket oscillator is removed;
433
+ wind/owl remain. `AMBIENCE_LEVELS` holds the levels. Footfall bodies have
434
+ 150–220 Hz high-pass filters; thumps are 40% lighter and decay in 55 ms,
435
+ including landings. The existing compressor stays on the opt-in master.
109
436
  - **Cabinets** (contract v1.7): a `HubDoor` with `"kind": "cabinet"` whose
110
437
  board from ghost carries `classic` is a door to a classic Castle deck the
111
438
  host plays itself. `hub.doors()` says `classic: true` once the board is
@@ -119,6 +446,12 @@ it is what every published hub game depends on.
119
446
  - `npm run check` bundles the deck and runs this kit's contract check; it must
120
447
  pass before `save-deck`, which runs the same check and refuses to publish.
121
448
 
449
+ - **Your games** (contract v1.54): deck-level `hub.yourGames: true` opts towns
450
+ into private hearted/recent rows and an arrival/return offer. The kit calls
451
+ `Hub.hearts()` once per signed-in town visit and `Hub.setHearts(doorIds)` on
452
+ a heart tap (at most eight, oldest first). No browser storage; no command or
453
+ new chrome in a deck without the key. `hub.results(playerId)` is unchanged.
454
+
122
455
  ## What is where
123
456
 
124
457
  | file | what it is |
@@ -129,26 +462,42 @@ it is what every published hub game depends on.
129
462
  | `code/server/actors.js` | `hub.move` and `hub.tint`: kinematic actors driven by the server, painted actors under a budget |
130
463
  | `code/server/grab.js`, `code/client/grab.js` | grabbing and throwing (v1.3): the server's checks, hook and `hub.drop`; the client's button, hold and throw |
131
464
  | `code/server/idle.js`, `code/client/idle.js`, `code/client/sound.js` | idle play (v1.6): emotes, seats and sounds; the server's checks, hooks and `hub.emote` / `hub.seat` / `hub.sound`; the client's picker, Sit / Stand, avatar motion and audio |
465
+ | `code/client/soundscape.js` | the soundscape (v1.42, v1.49, a deck with `hub.soundscape`): NPC babble, mapped footsteps, opt-in zone ambience/music, UI cues and the sound control's level, synthesised in WebAudio; the control itself is `chrome.js` `soundControl` |
466
+ | `code/client/soundscapeVoice.js` | v1.56 four original round-6 NPC voice types, bounded word plan, per-context source/gate waves/noise and complete three-source cleanup |
467
+ | `code/client/soundscapeMap.js`, `code/client/soundscapeAmbience.js` | v1.49 scene bounds, path and spot geometry; bounded synthesised beds, cross-fades, music and jukebox ducking |
468
+ | `code/client/soundscapeCrowd.js`, `code/client/soundscapeMarket.js`, `code/client/soundscapeSimlish.js` | v1.50 round-3 stadium crowd A and alternating distant market speakers, fixed voice pools and damped echoes |
469
+ | `code/client/soundscapeBusker.js` | v1.60 original placeholder jig/waltz, actor leases and one loudest loop, separate private pass, fixed voice pools and fade cleanup on the UI bus |
470
+ | `code/client/soundscapeUi.js` | v1.49 opt-in door, private timer and chip cues; two voices, four starts per second, departure tail and settled arrival |
471
+ | `code/shared/cues.js`, `code/server/cues.js` | v1.50 closed cue names, private/actor delivery and server token buckets |
472
+ | `code/client/soundscapeCues.js`, `code/client/soundscapeActions.js`, `code/client/soundscapeCourt.js` | v1.50 chosen action/court voices, bounded part scheduling and existing-state action edges |
473
+ | `code/client/soundscapeMusic.js`, `code/client/soundscapeMusicEngine.js`, `code/client/soundscapeSongs.js`, `code/client/soundscapeSongsRound3.js` | v1.50 selected round-2/3 scores, fixed voice pools, seeded bar-boundary alternation and calibrated music levels |
474
+ | `code/client/soundscapeSynthesis.js`, `code/client/soundscapeWaves.js` | shared audition noise/PeriodicWaves, graph cleanup and harbour A-rolled's calibrated swell/gull/creak voices |
132
475
  | `code/server/cabinets.js`, `code/client/cabinets.js` | cabinets (v1.7): the server's cards (bounded, sent per player in range inside a send budget) and the dev fixture; the client's kept cards and which one to draw |
133
476
  | `code/server/say.js`, `code/client/say.js` | quick reactions and canned phrases (v1.11): ids only, never text; the server's checks and fan-out, the client's words, bubbles and feed |
477
+ | `code/server/ballot.js`, `code/client/ballot.js` | the choice card (v1.68): the server's card checks, per-viewer views, tap checks, limits and `ballot` hook; the client's bottom sheet and its words from ids (`scripts/test-ballot.mjs`) |
134
478
  | `code/client/chat.js` | free-text chat (v1.12): polls the host for what this player may read and whom they reach, sends through it; who may chat is ghost's rule, never the kit's |
135
479
  | `code/server/party.js` | parties in a town (v1.10): invitations, a door proposed to the party, members put on its pad, `hub.coming`; a member away through a door is kept |
136
480
  | `code/client/together.js` | finding a friend in a town (v1.9): who here is one, the People list's rows, the pointers; the server's half (`hub-where`, `hub-goto`, the `where` hook) is in `code/server/hub.js` |
137
481
  | `code/server/wear.js` | wearables on the server: `hub.wear` (kept here and sent to ghost) and `hub.tryOn` (v1.28: kept here only, never sent to ghost), and what each client is told of both |
138
- | `code/client/wear.js`, `code/client/hats.js` | what players wear (v1.4) and how each hat is built; the hat ids, a list a place's server may import; each avatar's hat fit is in `avatar.js` |
482
+ | `code/client/wear.js`, `code/client/hats.js` | what players wear (v1.4), drawn under each avatar's own node (v1.41) so it moves and hides with it; the hat ids, a list a place's server may import; each avatar's hat fit is in `avatar.js` |
483
+ | `models/hats/<id>.pxmodel`, `scripts/gen-hats.mjs` | the sixteen hats' models (v1.41) and the script that writes them; `node scripts/gen-hats.mjs` after changing one, which test-hats.mjs checks |
484
+ | `code/shared/spin.js`, `code/client/spin.js` | turning displays (v1.55): the `HubSpin` rule shared with the check, and the client's per-frame turn |
139
485
  | `code/server/manifest.js` | reads and checks the `hub` block and results (plain JS, shared with the check) |
140
486
  | `code/server/place.js` | which place a session runs, from the session alone |
141
487
  | `code/server/game.js` | the starter game (Flag Dash), copied into a new deck |
142
488
  | `code/client/hookLayer.js` | the client hooks, layered under the deck's by `castle.real-time` |
143
489
  | `code/systems/hub.js` | the door trip, Back, joining a friend's layer, the HUD, labels, hidden actors, holds, the ribbon |
144
490
  | `code/client/chrome.js`, `state.js`, `avatar.js`, `firstJoin.js` | the DOM chrome, what the place declared, the avatar seam, the main place's first join (§13) |
145
- | `blueprints/avatar-<n>.scene`, `models/avatar-<n>.pxmodel`, `scripts/gen-avatars.mjs` | the four avatars (the Castle mascot, Petal, Beat, Star) and the script that writes their models; each avatar's height is in `avatar.js`, for what is worn over it |
491
+ | `blueprints/avatar-<n>.scene`, `models/avatar-<n>.pxmodel`, `scripts/gen-avatars.mjs`, `code/client/avatarFaces.js` | the sixteen toon avatars (the Castle mascot, Petal, Beat, Star; v1.51: Biscuit, Mochi, Hop, Pip, Ribbit, Ember, Bolt, Gloop, Cap, Toast, Scoop, Zest) and the script that writes their models and the picker's faces; each avatar's height and hat fit are in `avatar.js`, for what is worn over it. A guest with no stored choice may be given any of the sixteen; ghost defaults new accounts from its user-id cutoff on across all sixteen, while an existing account below it that never picked keeps one of the first four. Stored choices stay unchanged (contract §11) |
146
492
  | `scripts/gen-avatars-blocky.mjs`, `gen-avatars-bean.mjs`, `gen-avatars-pixel.mjs` | the scripts that write the other three sets' models (and blocky's and pixel's drawings); each set is the Castle mascot and three characters of its own |
147
- | `blueprints/<style>/avatar-<n>.scene`, `models/<style>/`, `drawings/<style>/` | the other avatar sets (`blocky`, `bean`, `pixel`): the same four avatar ids drawn another way, picked per viewer by `Avatar.style()` (the `hub_avatar_style` experiment, or `?hubStyle=` on localhost); toon unless one is assigned (contract §11) |
493
+ | `blueprints/<style>/avatar-<n>.scene`, `models/<style>/`, `drawings/<style>/` | the other avatar sets (`blocky`, `bean`, `pixel`): the first four avatar ids drawn another way (4-15 are drawn from toon's in every set), picked per viewer by `Avatar.style()` (the `hub_avatar_style` experiment, or `?hubStyle=` on localhost); toon unless one is assigned (contract §11) |
148
494
  | `scripts/check.mjs` | the publish check (`onCheck`) |
149
495
  | `scripts/pack.mjs` | the content pack exporter (`onPack`): the deck's client half as data, for another deck's engine (`docs/content-pack.md`) |
150
496
  | `code/client/pack.js`, `packFormat.js`, `sha256.js` | mounting a pack: fetch, verify, validate, build content |
151
497
  | `scripts/test-manifest.mjs`, `test-pack.mjs`, `test-actors.mjs`, `test-idle.mjs`, `test-classic.mjs` | tests over the manifest, results, place resolution, the pack, moved and painted actors, idle play, and cabinets |
498
+ | `scripts/test-avatar.mjs`, `test-avatar-models.mjs`, `test-picker.mjs` | the avatar seam; the toon models held to the generator and to 1,500 triangles and 8 draw calls (the engine's own count); the character picker |
499
+ | `code/client/avatarCap.js`, `scripts/test-avatar-cap.mjs` | a limit on different characters drawn at once, by default all sixteen (no stand-ins); with `?hubAvDistinct=N`, at most N (the local player's included): the farthest players past that are drawn as their stand-in (`avatar % 4`), never anyone within 8 m, with hysteresis, respawned through the hook layer's avatar-change path; client display only. `?hubAvDistinct=N` sets the limit (absent or 0 the default) |
500
+ | `code/client/avatarShare.js`, `scripts/test-avatar-share.mjs` | different characters drawn from shared materials (one per look), so a crowd of different characters switches material and program about as often as copies of one; `?hubAvShare=0` off, `?hubAvShare=sort` adds an opaque order that keeps one geometry's draws together (off by default: it bought nothing on the TECNO) |
152
501
 
153
502
  ## Rules for editing this kit
154
503
 
@@ -169,3 +518,92 @@ describe themselves, and hub games are Castle-authored only until the door
169
518
  table and curation exist (HUB.md decision 10). `castle-web init --kit
170
519
  hub-game` works regardless. Adding the description is the switch that offers
171
520
  it.
521
+
522
+ Town performance opt-in: `hub.companionIdle: true` in the deck's `castle.json`
523
+ ticks a settled shoulder companion or waiting guide at 5 Hz and avoids unchanged appearance
524
+ and transform writes. Movement, speech, pose, visibility and reconnect changes
525
+ wake it on the next frame. Unset, companion updates run as before. The world
526
+ assembly enables this only with `COMPANION_IDLE=1 COMPANION=1`.
527
+
528
+ Town Low update opt-in: `hub.lowActorBudget: true` (`LOW_ACTOR_BUDGET=1` in
529
+ town assembly) budgets HubNpc/HubSpin behavior and model animation to 10 Hz
530
+ beyond 12 m of the player. Near actors, avatars and High keep full cadence.
531
+ Physics and event dispatch still run every frame. The client owns the optional
532
+ `actor.runtime.updateEvery` seconds and node `userData.animationEvery` seconds;
533
+ removing them restores the original cadence. No authored component is changed.
534
+
535
+ Town Low distance opt-in: `LOW_ACTOR_DISTANCE=1` writes
536
+ `hub.lowActorDistance: true` and positive `lowDrawDistance` metres beside an
537
+ authored actor's `id`. The town writes 18 m for NPCs and 24 m for fixed
538
+ scenery, preserving keep/Low-only actors and gameplay movers. Low checks
539
+ scenery bounds against the camera (NPCs use their origin), then detaches far
540
+ nodes and pauses their render synchronization. The live Transform is still
541
+ checked every 500 ms so actors return; High restores authored rendering.
542
+ Physics, network and collision remain active. Without the flag, metadata is
543
+ ignored and existing distances apply.
544
+
545
+ The Low budget also applies to the separate HubSpin controller, so distant
546
+ display rotations write at the chosen cadence. Restoring near/High cadence
547
+ flushes pending elapsed time. Model walk and authored motion share a tick
548
+ to preserve their composed pose between updates.
549
+
550
+ Town play entry opt-in: use `/imports/castle.hub-game/play.jsx` as the
551
+ index.html module entry and set `hub.playOnlyEntry: true` in castle.json.
552
+ The ordinary main.jsx entry remains the default. The explicit entry uses the
553
+ same 3d runtime and file map without React or the official behavior inspectors;
554
+ its development edit route loads the ordinary editor. It requires the matching
555
+ physics-2d and physics-3d kits carrying `play/behaviors` and `playerRun`.
556
+ Custom deck behaviors keep the ordinary discovery order and may bring their
557
+ own UI dependencies. Official behavior sources stay in `behaviors/`; after
558
+ editing them, run `npm run sync:play-behaviors` at the repository root to
559
+ regenerate the runtime mirrors. The build checks their executable members and
560
+ byte-exact generation.
561
+
562
+ Optional `hub.loadTimings: true` exposes `globalThis.__hubLoadTimings` from
563
+ both entries. Events cover runtime creation, first scene synchronization and
564
+ render, image decode promises, and observed join/placement. Image promise time
565
+ includes loading and queueing; join/placement observations have 50 ms polling
566
+ resolution. The probe does not wait for images and is absent by default.
567
+
568
+ ### Optional distant avatar bodies
569
+
570
+ `hub.mergeFarAvatars: true` opts a hub into simpler distant remote avatars on
571
+ Low. Beyond 12 metres, compatible model bodies are merged in their resting
572
+ pose, without body outlines or cast shadows; within 10 metres the current
573
+ animated rig returns. Distance is checked every 250 ms. The local avatar,
574
+ High, the editor and content packs retain their normal bodies. Names, worn
575
+ objects, movement, physics and wire data are unchanged. The hidden rig still
576
+ animates, so this reduces drawing rather than animation CPU work.
577
+
578
+ The key is absent by default. Models with textures, transparent materials,
579
+ custom per-mesh rendering, reflected part transforms or incompatible geometry
580
+ retain their normal rig;
581
+ models waiting for deferred look baking are retried when ready. Owned merged
582
+ geometries are shared while in use and released when the last user leaves.
583
+
584
+
585
+ `hub.weakestTier: true` with `hub.tiers: true` opts into the v1.97 weakest-phone
586
+ profile. Auto/Low use it on PowerVR GE8xxx; High overrides it, and a manual
587
+ Weakest choice is available only in opted-in decks. A scene's `weakestDistricts`
588
+ physical table controls sleeping outside the active district (four-metre apron).
589
+ The profile preserves actor state/ID lookup, skips outline/AO bakes, defers look
590
+ work, caps both renderer and composer pixel ratios at 0.5, and uses the existing
591
+ far-body merge with twelve nearest full rigs. Leaving the profile restores the
592
+ previous buffer ratios unless another owner has changed them.
593
+ Unmapped actors, route anchors and dynamic bodies stay live. Games mounted
594
+ through doors use their ordinary tier path. See docs/contract.md for the schema.
595
+
596
+ - **Bounded shots** (v1.119): optional `fit: {min:{x,y,z}, max:{x,y,z}, minDistance}`
597
+ on hub.shot fits a world box inside the central 90% of the current perspective
598
+ canvas. Coordinates ±10000, ordered spans ≤1000, minDistance in (0,1000].
599
+ Absent fit keeps the authored distance. Wire bounds own lease equality;
600
+ resizing changes only the drawn distance, preserving shot identity/lifecycle.
601
+
602
+
603
+ `hub.playCards: true` (v1.122) offers canned play-phrase Go cards to mutual
604
+ friends and party members anywhere in the layer, and strangers within 12 m.
605
+ Only one stranger card is retained at a time; each stranger has a 60 s
606
+ cooldown across doors. Bubble/feed and blocks are unchanged. Absent/false
607
+ keeps the existing policy.
608
+
609
+ `hub.highOnly: true` with `hub.tiers: true` reserves `tier: "high"` Transform/Shape/Model decor for High; Low/Middle/Weakest skip it before load and High restores it in 8 ms slices, independently of `hub.quality`. Editor and door content are unchanged.