castle-web-cli 0.4.232 → 0.4.233

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 (355) 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/castle-host/host.d.ts +1 -0
  8. package/dist/castle-host/host.js +51 -3
  9. package/dist/castleJson.d.ts +4 -2
  10. package/dist/castleJson.js +2 -0
  11. package/dist/check.d.ts +3 -1
  12. package/dist/check.js +11 -1
  13. package/dist/devSessionStorage.js +47 -1
  14. package/dist/importPinMismatch.d.ts +22 -0
  15. package/dist/importPinMismatch.js +77 -0
  16. package/dist/importRegression.js +3 -15
  17. package/dist/imports.d.ts +10 -3
  18. package/dist/imports.js +88 -20
  19. package/dist/index.js +5 -4
  20. package/dist/init.js +1 -1
  21. package/dist/platformDoc.js +22 -0
  22. package/dist/routerFences.d.ts +5 -0
  23. package/dist/routerFences.js +12 -2
  24. package/dist/save-deck.d.ts +5 -0
  25. package/dist/save-deck.js +37 -4
  26. package/dist/serve.js +3 -0
  27. package/dist/shell/assets/{index-D2tWM896.js → index-BjOxR-lW.js} +4 -4
  28. package/dist/shell/assets/index-MVLfNYd9.css +1 -0
  29. package/dist/shell/index.html +2 -2
  30. package/dist/taskSteer.d.ts +13 -0
  31. package/dist/taskSteer.js +22 -2
  32. package/kits/base/castle.json +1 -1
  33. package/kits/base/package-lock.json +1 -1
  34. package/kits/base/sdk/README.md +79 -2
  35. package/kits/base/sdk/avatar.d.ts +6 -2
  36. package/kits/base/sdk/avatar.js +12 -4
  37. package/kits/base/sdk/castle.d.ts +1 -1
  38. package/kits/base/sdk/commands.d.ts +14 -0
  39. package/kits/base/sdk/hub.d.ts +6 -2
  40. package/kits/base/sdk/hub.js +13 -0
  41. package/kits/base/sdk/multiplayer.js +17 -1
  42. package/kits/base/sdk/save.js +2 -1
  43. package/kits/base/sdk/server/hub.d.ts +87 -0
  44. package/kits/base/sdk/server/hub.js +70 -0
  45. package/kits/base/sdk/server/platformHandle.d.ts +31 -1
  46. package/kits/base/sdk/server/storage.d.ts +13 -0
  47. package/kits/base/sdk/server/storage.js +46 -0
  48. package/kits/base/sdk/server/wrapper.d.ts +36 -5
  49. package/kits/base/sdk/server/wrapper.js +83 -8
  50. package/kits/hub-game/CLAUDE.md +329 -11
  51. package/kits/hub-game/blueprints/avatar-10.scene +28 -0
  52. package/kits/hub-game/blueprints/avatar-11.scene +28 -0
  53. package/kits/hub-game/blueprints/avatar-12.scene +28 -0
  54. package/kits/hub-game/blueprints/avatar-13.scene +28 -0
  55. package/kits/hub-game/blueprints/avatar-14.scene +28 -0
  56. package/kits/hub-game/blueprints/avatar-15.scene +28 -0
  57. package/kits/hub-game/blueprints/avatar-4.scene +28 -0
  58. package/kits/hub-game/blueprints/avatar-5.scene +28 -0
  59. package/kits/hub-game/blueprints/avatar-6.scene +28 -0
  60. package/kits/hub-game/blueprints/avatar-7.scene +28 -0
  61. package/kits/hub-game/blueprints/avatar-8.scene +28 -0
  62. package/kits/hub-game/blueprints/avatar-9.scene +28 -0
  63. package/kits/hub-game/code/client/actorBudget.js +47 -0
  64. package/kits/hub-game/code/client/attention.js +11 -2
  65. package/kits/hub-game/code/client/avatar.js +309 -35
  66. package/kits/hub-game/code/client/avatarCap.js +228 -0
  67. package/kits/hub-game/code/client/avatarColors.js +70 -0
  68. package/kits/hub-game/code/client/avatarFaces.js +21 -0
  69. package/kits/hub-game/code/client/avatarShare.js +251 -0
  70. package/kits/hub-game/code/client/ballot.js +467 -0
  71. package/kits/hub-game/code/client/build.js +22 -0
  72. package/kits/hub-game/code/client/chrome.js +1144 -50
  73. package/kits/hub-game/code/client/companion.js +716 -0
  74. package/kits/hub-game/code/client/companionDress.js +99 -0
  75. package/kits/hub-game/code/client/decor.js +509 -0
  76. package/kits/hub-game/code/client/earned.js +131 -0
  77. package/kits/hub-game/code/client/emoteBubble.js +75 -0
  78. package/kits/hub-game/code/client/grab.js +339 -20
  79. package/kits/hub-game/code/client/hookLayer.js +299 -13
  80. package/kits/hub-game/code/client/idle.js +163 -22
  81. package/kits/hub-game/code/client/interestCap.js +81 -0
  82. package/kits/hub-game/code/client/keys.js +36 -0
  83. package/kits/hub-game/code/client/labelsNear.js +205 -0
  84. package/kits/hub-game/code/client/menuIcons.js +34 -0
  85. package/kits/hub-game/code/client/pack.js +6 -2
  86. package/kits/hub-game/code/client/packFormat.js +3 -3
  87. package/kits/hub-game/code/client/rehello.js +167 -0
  88. package/kits/hub-game/code/client/shot.js +92 -0
  89. package/kits/hub-game/code/client/sound.js +63 -8
  90. package/kits/hub-game/code/client/soundscape.js +1151 -0
  91. package/kits/hub-game/code/client/soundscapeActions.js +99 -0
  92. package/kits/hub-game/code/client/soundscapeAmbience.js +453 -0
  93. package/kits/hub-game/code/client/soundscapeBaked.js +143 -0
  94. package/kits/hub-game/code/client/soundscapeBusker.js +217 -0
  95. package/kits/hub-game/code/client/soundscapeCourt.js +200 -0
  96. package/kits/hub-game/code/client/soundscapeCrowd.js +331 -0
  97. package/kits/hub-game/code/client/soundscapeCues.js +362 -0
  98. package/kits/hub-game/code/client/soundscapeMap.js +181 -0
  99. package/kits/hub-game/code/client/soundscapeMarket.js +176 -0
  100. package/kits/hub-game/code/client/soundscapeMusic.js +126 -0
  101. package/kits/hub-game/code/client/soundscapeMusicEngine.js +460 -0
  102. package/kits/hub-game/code/client/soundscapeSimlish.js +737 -0
  103. package/kits/hub-game/code/client/soundscapeSongs.js +127 -0
  104. package/kits/hub-game/code/client/soundscapeSongsRound3.js +63 -0
  105. package/kits/hub-game/code/client/soundscapeSynthesis.js +168 -0
  106. package/kits/hub-game/code/client/soundscapeUi.js +211 -0
  107. package/kits/hub-game/code/client/soundscapeVoice.js +1209 -0
  108. package/kits/hub-game/code/client/soundscapeWaves.js +206 -0
  109. package/kits/hub-game/code/client/spin.js +101 -0
  110. package/kits/hub-game/code/client/state.js +109 -1
  111. package/kits/hub-game/code/client/stuck.js +259 -0
  112. package/kits/hub-game/code/client/talk.js +538 -47
  113. package/kits/hub-game/code/client/tiers.js +516 -27
  114. package/kits/hub-game/code/client/toastBand.js +37 -0
  115. package/kits/hub-game/code/client/together.js +32 -0
  116. package/kits/hub-game/code/client/visibility.js +43 -0
  117. package/kits/hub-game/code/client/wear.js +461 -170
  118. package/kits/hub-game/code/client/yours.js +199 -0
  119. package/kits/hub-game/code/companionSpec.js +45 -0
  120. package/kits/hub-game/code/privateText.js +7 -0
  121. package/kits/hub-game/code/server/actions.js +133 -0
  122. package/kits/hub-game/code/server/actors.js +9 -1
  123. package/kits/hub-game/code/server/ask.js +155 -0
  124. package/kits/hub-game/code/server/ballot.js +539 -0
  125. package/kits/hub-game/code/server/cells.js +100 -0
  126. package/kits/hub-game/code/server/companion.js +82 -0
  127. package/kits/hub-game/code/server/cues.js +70 -0
  128. package/kits/hub-game/code/server/decor.js +269 -0
  129. package/kits/hub-game/code/server/earned.js +461 -0
  130. package/kits/hub-game/code/server/friendBests.js +166 -0
  131. package/kits/hub-game/code/server/friendsAmong.js +232 -0
  132. package/kits/hub-game/code/server/history.js +5 -0
  133. package/kits/hub-game/code/server/hub.js +1254 -50
  134. package/kits/hub-game/code/server/idle.js +30 -11
  135. package/kits/hub-game/code/server/index.js +2 -2
  136. package/kits/hub-game/code/server/labels.js +28 -2
  137. package/kits/hub-game/code/server/manifest.js +378 -7
  138. package/kits/hub-game/code/server/menu.js +133 -0
  139. package/kits/hub-game/code/server/npcs.js +830 -80
  140. package/kits/hub-game/code/server/party.js +2 -2
  141. package/kits/hub-game/code/server/players.js +22 -0
  142. package/kits/hub-game/code/server/shot.js +110 -0
  143. package/kits/hub-game/code/server/standing.js +124 -0
  144. package/kits/hub-game/code/server/vis.js +113 -0
  145. package/kits/hub-game/code/server/wear.js +12 -0
  146. package/kits/hub-game/code/server/yours.js +59 -0
  147. package/kits/hub-game/code/shared/cues.js +9 -0
  148. package/kits/hub-game/code/shared/decor.js +41 -0
  149. package/kits/hub-game/code/shared/shot.js +19 -0
  150. package/kits/hub-game/code/shared/spin.js +57 -0
  151. package/kits/hub-game/code/systems/hub.js +845 -95
  152. package/kits/hub-game/docs/content-pack.md +1 -1
  153. package/kits/hub-game/docs/contract.md +2244 -61
  154. package/kits/hub-game/docs/home-pieces.md +64 -0
  155. package/kits/hub-game/models/avatar-10.pxmodel +28 -0
  156. package/kits/hub-game/models/avatar-11.pxmodel +28 -0
  157. package/kits/hub-game/models/avatar-12.pxmodel +27 -0
  158. package/kits/hub-game/models/avatar-13.pxmodel +24 -0
  159. package/kits/hub-game/models/avatar-14.pxmodel +29 -0
  160. package/kits/hub-game/models/avatar-15.pxmodel +24 -0
  161. package/kits/hub-game/models/avatar-4.pxmodel +29 -0
  162. package/kits/hub-game/models/avatar-5.pxmodel +27 -0
  163. package/kits/hub-game/models/avatar-6.pxmodel +26 -0
  164. package/kits/hub-game/models/avatar-7.pxmodel +25 -0
  165. package/kits/hub-game/models/avatar-8.pxmodel +24 -0
  166. package/kits/hub-game/models/avatar-9.pxmodel +30 -0
  167. package/kits/hub-game/models/earned/badge-round.pxmodel +100 -0
  168. package/kits/hub-game/models/earned/badge-shield.pxmodel +117 -0
  169. package/kits/hub-game/models/earned/badge-star.pxmodel +87 -0
  170. package/kits/hub-game/models/earned/belt-plain.pxmodel +72 -0
  171. package/kits/hub-game/models/earned/held-ball.pxmodel +43 -0
  172. package/kits/hub-game/models/earned/held-lantern.pxmodel +85 -0
  173. package/kits/hub-game/models/earned/held-net.pxmodel +57 -0
  174. package/kits/hub-game/models/earned/held-trophy.pxmodel +109 -0
  175. package/kits/hub-game/models/earned/pin-round.pxmodel +62 -0
  176. package/kits/hub-game/models/earned/sash-plain.pxmodel +66 -0
  177. package/kits/hub-game/models/earned/square/belt-plain.pxmodel +104 -0
  178. package/kits/hub-game/models/earned/square/sash-plain.pxmodel +98 -0
  179. package/kits/hub-game/models/hats/bat-clip.pxmodel +206 -0
  180. package/kits/hub-game/models/hats/beekeeper.pxmodel +149 -0
  181. package/kits/hub-game/models/hats/cap.pxmodel +162 -0
  182. package/kits/hub-game/models/hats/captain.pxmodel +178 -0
  183. package/kits/hub-game/models/hats/crooked-top.pxmodel +172 -0
  184. package/kits/hub-game/models/hats/flower-crown.pxmodel +451 -0
  185. package/kits/hub-game/models/hats/foam-crown.pxmodel +179 -0
  186. package/kits/hub-game/models/hats/lantern.pxmodel +230 -0
  187. package/kits/hub-game/models/hats/laurel.pxmodel +533 -0
  188. package/kits/hub-game/models/hats/lighthouse.pxmodel +96 -0
  189. package/kits/hub-game/models/hats/sailor.pxmodel +141 -0
  190. package/kits/hub-game/models/hats/souwester.pxmodel +131 -0
  191. package/kits/hub-game/models/hats/straw.pxmodel +139 -0
  192. package/kits/hub-game/models/hats/sunflower.pxmodel +406 -0
  193. package/kits/hub-game/models/hats/sweatband.pxmodel +112 -0
  194. package/kits/hub-game/models/hats/witch.pxmodel +147 -0
  195. package/kits/hub-game/package-lock.json +2 -0
  196. package/kits/hub-game/package.json +2 -1
  197. package/kits/hub-game/scripts/check.mjs +78 -11
  198. package/kits/hub-game/scripts/companion-follower-wire.json +1 -0
  199. package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +121 -0
  200. package/kits/hub-game/scripts/fixtures/decor-keyless.json +293 -0
  201. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +23 -0
  202. package/kits/hub-game/scripts/fixtures/fake-dom.mjs +107 -0
  203. package/kits/hub-game/scripts/fixtures/interest-legacy.json +385 -0
  204. package/kits/hub-game/scripts/fixtures/npc-notes-v1.77.jsonl +4 -0
  205. package/kits/hub-game/scripts/fixtures/vis-shared-wire.json +1 -0
  206. package/kits/hub-game/scripts/gen-avatars.mjs +933 -16
  207. package/kits/hub-game/scripts/gen-earned.mjs +285 -0
  208. package/kits/hub-game/scripts/gen-hats.mjs +827 -0
  209. package/kits/hub-game/scripts/grab.before-orbit.mjs +400 -0
  210. package/kits/hub-game/scripts/soundscape-wave-analysis.mjs +125 -0
  211. package/kits/hub-game/scripts/test-actions-client.mjs +488 -0
  212. package/kits/hub-game/scripts/test-actions.mjs +298 -0
  213. package/kits/hub-game/scripts/test-actor-budget.mjs +44 -0
  214. package/kits/hub-game/scripts/test-actors.mjs +19 -17
  215. package/kits/hub-game/scripts/test-ask-client.mjs +358 -0
  216. package/kits/hub-game/scripts/test-ask.mjs +269 -0
  217. package/kits/hub-game/scripts/test-attention.mjs +10 -1
  218. package/kits/hub-game/scripts/test-avatar-cap.mjs +379 -0
  219. package/kits/hub-game/scripts/test-avatar-colors.mjs +72 -0
  220. package/kits/hub-game/scripts/test-avatar-models.mjs +181 -0
  221. package/kits/hub-game/scripts/test-avatar-share.mjs +318 -0
  222. package/kits/hub-game/scripts/test-avatar-wire.mjs +753 -0
  223. package/kits/hub-game/scripts/test-avatar.mjs +540 -7
  224. package/kits/hub-game/scripts/test-ballot.mjs +1001 -0
  225. package/kits/hub-game/scripts/test-build.mjs +31 -0
  226. package/kits/hub-game/scripts/test-cells.mjs +71 -0
  227. package/kits/hub-game/scripts/test-chat.mjs +662 -0
  228. package/kits/hub-game/scripts/test-classic.mjs +2 -0
  229. package/kits/hub-game/scripts/test-companion-chat.mjs +198 -0
  230. package/kits/hub-game/scripts/test-companion-client.mjs +1167 -0
  231. package/kits/hub-game/scripts/test-companion.mjs +259 -0
  232. package/kits/hub-game/scripts/test-decor-client.mjs +303 -0
  233. package/kits/hub-game/scripts/test-decor.mjs +457 -0
  234. package/kits/hub-game/scripts/test-earned-client.mjs +459 -0
  235. package/kits/hub-game/scripts/test-earned.mjs +1194 -0
  236. package/kits/hub-game/scripts/test-emote-bubble.mjs +110 -0
  237. package/kits/hub-game/scripts/test-friend-bests.mjs +435 -0
  238. package/kits/hub-game/scripts/test-grab-orbit.mjs +918 -0
  239. package/kits/hub-game/scripts/test-grab.mjs +7 -0
  240. package/kits/hub-game/scripts/test-hats.mjs +422 -168
  241. package/kits/hub-game/scripts/test-hub-leaving.mjs +203 -0
  242. package/kits/hub-game/scripts/test-hub-ops.mjs +439 -2
  243. package/kits/hub-game/scripts/test-hub-trip.mjs +716 -2
  244. package/kits/hub-game/scripts/test-hud-clear.mjs +328 -4
  245. package/kits/hub-game/scripts/test-idle.mjs +361 -1
  246. package/kits/hub-game/scripts/test-interest-cap.mjs +36 -0
  247. package/kits/hub-game/scripts/test-interest-cells.mjs +493 -0
  248. package/kits/hub-game/scripts/test-interest-client.mjs +118 -0
  249. package/kits/hub-game/scripts/test-keys.mjs +46 -1
  250. package/kits/hub-game/scripts/test-labels.mjs +596 -0
  251. package/kits/hub-game/scripts/test-manifest.mjs +207 -0
  252. package/kits/hub-game/scripts/test-menu-client.mjs +480 -0
  253. package/kits/hub-game/scripts/test-menu.mjs +296 -0
  254. package/kits/hub-game/scripts/test-npcs.mjs +1718 -12
  255. package/kits/hub-game/scripts/test-object-entry.mjs +76 -0
  256. package/kits/hub-game/scripts/test-pack.mjs +7 -0
  257. package/kits/hub-game/scripts/test-picker.mjs +314 -0
  258. package/kits/hub-game/scripts/test-rehello.mjs +1039 -0
  259. package/kits/hub-game/scripts/test-relations-among.mjs +222 -0
  260. package/kits/hub-game/scripts/test-relations-refresh.mjs +188 -0
  261. package/kits/hub-game/scripts/test-shot.mjs +756 -0
  262. package/kits/hub-game/scripts/test-soundscape.mjs +5432 -0
  263. package/kits/hub-game/scripts/test-spin.mjs +314 -0
  264. package/kits/hub-game/scripts/test-standing.mjs +416 -0
  265. package/kits/hub-game/scripts/test-stuck.mjs +1903 -0
  266. package/kits/hub-game/scripts/test-tier-cells.mjs +706 -0
  267. package/kits/hub-game/scripts/test-tiers-render.mjs +339 -0
  268. package/kits/hub-game/scripts/test-tiers.mjs +477 -2
  269. package/kits/hub-game/scripts/test-toast-band.mjs +61 -0
  270. package/kits/hub-game/scripts/test-try-on.mjs +22 -22
  271. package/kits/hub-game/scripts/test-vis.mjs +343 -0
  272. package/kits/hub-game/scripts/test-visibility.mjs +134 -0
  273. package/kits/hub-game/scripts/test-yours-chrome.mjs +166 -0
  274. package/kits/hub-game/scripts/test-yours.mjs +372 -0
  275. package/kits/multiplayer-3d/CLAUDE.md +50 -0
  276. package/kits/multiplayer-3d/castle.json +5 -5
  277. package/kits/multiplayer-3d/code/client/avatars.js +7 -0
  278. package/kits/multiplayer-3d/code/client/gait.js +65 -0
  279. package/kits/multiplayer-3d/code/client/nameTags.js +59 -4
  280. package/kits/multiplayer-3d/code/options.js +5 -0
  281. package/kits/multiplayer-3d/code/server/ownership.js +10 -2
  282. package/kits/multiplayer-3d/code/server/sceneBodies.js +12 -0
  283. package/kits/multiplayer-3d/code/server/world.js +7 -0
  284. package/kits/multiplayer-3d/code/systems/multiplayer.js +74 -4
  285. package/kits/multiplayer-3d/package.json +2 -1
  286. package/kits/multiplayer-3d/scripts/fixtures/README.md +11 -0
  287. package/kits/multiplayer-3d/scripts/fixtures/ownership-legacy.json +2 -0
  288. package/kits/multiplayer-3d/scripts/ownership-harness.mjs +102 -0
  289. package/kits/multiplayer-3d/scripts/ownership-loader.mjs +46 -0
  290. package/kits/multiplayer-3d/scripts/ownership-worker.mjs +15 -0
  291. package/kits/multiplayer-3d/scripts/record-ownership-session.mjs +98 -0
  292. package/kits/multiplayer-3d/scripts/test-eligible-claims.mjs +167 -0
  293. package/kits/multiplayer-3d/scripts/test-own-name-tag.mjs +247 -0
  294. package/kits/physics-2d/CLAUDE.md +9 -0
  295. package/kits/physics-2d/castle.json +2 -2
  296. package/kits/physics-2d/engine/scene.js +253 -1
  297. package/kits/physics-2d/engine/skyKey.js +129 -0
  298. package/kits/physics-2d/engine/stillClock.js +106 -0
  299. package/kits/physics-2d/engine/updateBudget.js +21 -0
  300. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +326 -1
  301. package/kits/physics-3d/CLAUDE.md +1169 -30
  302. package/kits/physics-3d/behaviors/Player.jsx +629 -72
  303. package/kits/physics-3d/castle.json +3 -3
  304. package/kits/physics-3d/docs/pxmodel-format.md +8 -0
  305. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +69 -13
  306. package/kits/physics-3d/engine3d/actornode.js +86 -0
  307. package/kits/physics-3d/engine3d/animationBudget.js +23 -0
  308. package/kits/physics-3d/engine3d/editorWorld.js +6 -0
  309. package/kits/physics-3d/engine3d/emptynodes.js +232 -0
  310. package/kits/physics-3d/engine3d/framecap.js +96 -0
  311. package/kits/physics-3d/engine3d/gait.js +118 -0
  312. package/kits/physics-3d/engine3d/kithooks.js +47 -0
  313. package/kits/physics-3d/engine3d/look.js +507 -48
  314. package/kits/physics-3d/engine3d/lookbake.js +208 -0
  315. package/kits/physics-3d/engine3d/materialpresets.js +2 -0
  316. package/kits/physics-3d/engine3d/motion.js +39 -10
  317. package/kits/physics-3d/engine3d/nearshadows.js +37 -19
  318. package/kits/physics-3d/engine3d/optimize.js +9 -5
  319. package/kits/physics-3d/engine3d/orbitinput.js +487 -9
  320. package/kits/physics-3d/engine3d/orbitlens.js +48 -0
  321. package/kits/physics-3d/engine3d/ownmodel.js +213 -0
  322. package/kits/physics-3d/engine3d/pxmodel.js +42 -11
  323. package/kits/physics-3d/engine3d/shadowfade.js +882 -0
  324. package/kits/physics-3d/engine3d/sky.js +547 -0
  325. package/kits/physics-3d/engine3d/skylife.js +306 -0
  326. package/kits/physics-3d/engine3d/unchanged.js +11 -0
  327. package/kits/physics-3d/engine3d/viewrange.js +52 -0
  328. package/kits/physics-3d/engine3d/world3d.js +796 -69
  329. package/kits/physics-3d/main.jsx +5 -0
  330. package/kits/physics-3d/package.json +1 -1
  331. package/kits/physics-3d/scripts/look-baseline.mjs +155 -0
  332. package/kits/physics-3d/scripts/test-camera-orbit.mjs +2563 -80
  333. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +1 -1
  334. package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +435 -0
  335. package/kits/physics-3d/scripts/test-frame-cap.mjs +452 -0
  336. package/kits/physics-3d/scripts/test-gait.mjs +387 -0
  337. package/kits/physics-3d/scripts/test-look-bake.mjs +1056 -0
  338. package/kits/physics-3d/scripts/test-model-parse-cache.mjs +92 -0
  339. package/kits/physics-3d/scripts/test-near-shadows.mjs +3 -0
  340. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +1920 -0
  341. package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +545 -0
  342. package/kits/physics-3d/scripts/test-orbit-shot.mjs +583 -0
  343. package/kits/physics-3d/scripts/test-orbit-view.mjs +230 -0
  344. package/kits/physics-3d/scripts/test-skip-empty-nodes.mjs +845 -0
  345. package/kits/physics-3d/scripts/test-sky.mjs +2470 -0
  346. package/kits/physics-3d/scripts/test-static-actors.mjs +8 -1
  347. package/kits/physics-3d/scripts/test-static-scenery.mjs +2171 -0
  348. package/kits/physics-3d/scripts/test-steady-hover.mjs +2 -0
  349. package/kits/physics-3d/scripts/test-view-range.mjs +260 -0
  350. package/kits/physics-3d/systems/physics3d.js +383 -6
  351. package/kits/real-time/castle.json +2 -2
  352. package/kits/real-time/code/server/gameHooks.js +7 -0
  353. package/kits/real-time/code/server/session.js +97 -19
  354. package/package.json +2 -2
  355. package/dist/shell/assets/index-Cf61cNfT.css +0 -1
@@ -69,18 +69,15 @@ async function bootSession(platformHandle, callbacks) {
69
69
  players: Object.freeze(request.audience.players.map((player) => Object.freeze(joinedPlayer(player.playerId, player)))),
70
70
  characterIds: Object.freeze([...request.audience.characterIds]),
71
71
  }),
72
- async send() {
72
+ async send(options) {
73
73
  if (settled)
74
74
  throw new TypeError("This shared character request is already settled.");
75
75
  settled = true;
76
- let rawReceipt;
77
- try {
78
- rawReceipt = await platformHandle.worldCharacterSend(request.grantId);
79
- }
80
- catch (error) {
76
+ const rawReceipt = await sendWorldCharacterTurn(platformHandle, request.grantId, options)
77
+ .catch((error) => {
81
78
  brokerFailure.rejection = { error };
82
79
  throw error;
83
- }
80
+ });
84
81
  return parseWorldCharacterAdmission(rawReceipt, request.operationId);
85
82
  },
86
83
  reject(code) {
@@ -103,6 +100,7 @@ async function bootSession(platformHandle, callbacks) {
103
100
  }
104
101
  });
105
102
  }
103
+ listenForWorldCharacterTools(platformHandle, callbacks, session);
106
104
  if (callbacks.onWorldCharacterCommand &&
107
105
  hasWorldCharacterPlatform(platformHandle, "worldCharacterCommand")) {
108
106
  platformHandle.on("worldCharacterCommand", async (raw) => {
@@ -1081,12 +1079,13 @@ function assertRuntimeCharacterCapabilities(value) {
1081
1079
  }
1082
1080
  return Object.freeze({ actionIds: Object.freeze([...normalized].sort()) });
1083
1081
  }
1082
+ const LONE_SURROGATE = /[\uD800-\uDFFF]/u;
1084
1083
  function assertRuntimeCharacterText(value, field, maxCharacters, maxBytes) {
1085
1084
  if (typeof value !== "string" ||
1086
1085
  value.length === 0 ||
1087
1086
  value.length > maxCharacters ||
1088
1087
  value.includes("\0") ||
1089
- /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(value) ||
1088
+ LONE_SURROGATE.test(value) ||
1090
1089
  new TextEncoder().encode(value).byteLength > maxBytes) {
1091
1090
  throw new TypeError(`session.world.characters.create: ${field} must be valid non-empty text of at most ${maxCharacters} characters.`);
1092
1091
  }
@@ -1190,6 +1189,82 @@ function assertPlatformWorldCharacterRead(value) {
1190
1189
  }
1191
1190
  return value;
1192
1191
  }
1192
+ // Tools ride only to a host that can answer them (an older host refuses a send
1193
+ // carrying anything beyond the grant); otherwise this is exactly the tool-less send.
1194
+ function sendWorldCharacterTurn(platformHandle, grantId, options) {
1195
+ const tools = options?.tools;
1196
+ return Array.isArray(tools) && tools.length > 0 &&
1197
+ typeof platformHandle.worldCharacterToolResult === "function"
1198
+ ? platformHandle.worldCharacterSend(grantId, tools)
1199
+ : platformHandle.worldCharacterSend(grantId);
1200
+ }
1201
+ // Only a handler on a host that answers place tools listens; without one the
1202
+ // host times the lookup out and the character answers without it.
1203
+ function listenForWorldCharacterTools(platformHandle, callbacks, session) {
1204
+ const handler = callbacks.onWorldCharacterTool;
1205
+ const answer = platformHandle.worldCharacterToolResult?.bind(platformHandle);
1206
+ if (!handler || !answer)
1207
+ return;
1208
+ try {
1209
+ platformHandle.on("worldCharacterTool", async (raw) => {
1210
+ const call = platformWorldCharacterTool(raw);
1211
+ if (!call)
1212
+ return;
1213
+ const result = await worldCharacterToolResult(handler, call.request, session);
1214
+ try {
1215
+ await answer(call.requestId, result);
1216
+ }
1217
+ catch {
1218
+ // The host has stopped waiting (or refused); the character answers without it.
1219
+ }
1220
+ });
1221
+ }
1222
+ catch {
1223
+ // Older shims may reject event names they do not recognize.
1224
+ }
1225
+ }
1226
+ const MAX_WORLD_CHARACTER_TOOL_RESULT_BYTES = 1024;
1227
+ const WORLD_CHARACTER_TOOL_TOO_LARGE = '{"error":"result too large"}';
1228
+ const WORLD_CHARACTER_TOOL_FAILED = '{"error":"tool failed"}';
1229
+ function platformWorldCharacterTool(value) {
1230
+ if (!value ||
1231
+ typeof value !== "object" ||
1232
+ typeof value.requestId !== "string" ||
1233
+ typeof value.operationId !== "string" ||
1234
+ typeof value.characterId !== "string" ||
1235
+ typeof value.playerId !== "string" ||
1236
+ typeof value.name !== "string" ||
1237
+ !value.input ||
1238
+ typeof value.input !== "object" ||
1239
+ Array.isArray(value.input)) {
1240
+ return null;
1241
+ }
1242
+ return {
1243
+ requestId: value.requestId,
1244
+ request: Object.freeze({
1245
+ operationId: value.operationId,
1246
+ characterId: value.characterId,
1247
+ playerId: value.playerId,
1248
+ name: value.name,
1249
+ input: deepFreezeJsonObject(value.input),
1250
+ }),
1251
+ };
1252
+ }
1253
+ async function worldCharacterToolResult(handler, request, session) {
1254
+ let result;
1255
+ try {
1256
+ const value = await handler(request, session);
1257
+ result = typeof value === "string" ? value : JSON.stringify(value);
1258
+ }
1259
+ catch {
1260
+ return WORLD_CHARACTER_TOOL_FAILED;
1261
+ }
1262
+ if (typeof result !== "string")
1263
+ return WORLD_CHARACTER_TOOL_FAILED;
1264
+ return new TextEncoder().encode(result).byteLength > MAX_WORLD_CHARACTER_TOOL_RESULT_BYTES
1265
+ ? WORLD_CHARACTER_TOOL_TOO_LARGE
1266
+ : result;
1267
+ }
1193
1268
  function hasWorldCharacterPlatform(platformHandle, operation) {
1194
1269
  return (typeof platformHandle[operation] === "function" &&
1195
1270
  typeof platformHandle.worldCharacterReject === "function");
@@ -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.79; 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. -->
@@ -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,19 +79,95 @@ 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
+ Close, replacement without it, leave and higher-priority UI release it;
94
+ absent `face` preserves control and wire bytes. Bounds and validation: contract
95
+ §9; `scripts/test-menu.mjs` and `test-menu-client.mjs`. No absent-key API,
96
+ hook lookup, state, chrome or wire bytes.
97
+ - **Owner and decorating** (v1.67): `hub.owner` is the platform owner's user id
98
+ or null; `hub.house: { devOwner: "first" }` keeps the first dev arrival as
99
+ owner for the session. A place with `hub.decor: { grid: { origin, w, d,
100
+ cell }, layers }` gets private `hub.decor.button/open/close/update` and the
101
+ `decor(hub, playerId, op)` hook: the kit draws the grid, catalogue, ghosts
102
+ and touch/mouse controls; the deck checks ownership, stock, collisions and
103
+ saving, then applies spawn/move/despawn/tint and updates the catalogue.
104
+ Spawned seats work for guests in these places. Contract §10 Decorating;
105
+ `scripts/test-decor.mjs` and `test-decor-client.mjs`. Absent keys add no wire
106
+ state, chrome or preview resources.
107
+ - **Per-viewer visibility** (v1.62): `hub.hide/show(actorId, { to: [playerIds] })`
108
+ replaces shared visibility for those connected players; either with
109
+ `clear: true` restores the shared view. Works for baked Models. Unknown or
110
+ disconnected players are ignored; at most 256 actor overrides per player.
111
+ Private calls return true when taken; invalid actor/options or exceeding the
112
+ cap warn once and return false without changes. Leaving drops overrides.
113
+ Client drawing, pads, idle and soundscape use the merged visibility; server
114
+ bodies and shared visibility logic (pads, labels, doors, idle) stay unchanged.
115
+ Shared-only places send exactly the same snapshots, deltas and messages.
116
+ - **Moment shots** (v1.61): `hub.shot(playerId, { look: { x, y, z }, distance,
117
+ pitch, yaw })` privately blends and holds the orbit camera; `null` clears.
118
+ Finite values, distance > 0 m, angles in degrees, pitch capped at ±89. The
119
+ place scene must use `cameraControl: "orbit"`; the shot is not collided.
120
+ Four changed shots/s (burst four), equal poses suppressed for 1 s; clears
121
+ bypass the budget. True when sent, false and warn once otherwise; invalid
122
+ poses warn once and clear. The client clears on travel, leave, scene
123
+ load/place change and disconnect, preserving shots assigned by deck code.
124
+ The server renews a held pose every 2 s and immediately on a fresh join,
125
+ without spending the rate budget. Equal renewals keep the same shot object.
126
+ Renewals restore a shot lost to a disconnect, but never re-create one dropped
127
+ for a scene load, travel, round end or a deck's own `orbitShot`; only a fresh
128
+ `hub.shot` call does that. Travel and round end stop server renewals.
129
+ The client drops a shot not renewed for 5 s, on its first watcher run even
130
+ after a background-tab pause, so it cannot outlive its server or connection.
131
+ No client code or manifest key needed.
132
+ - **The choice card** (v1.68): `"ballot": { "lines": [{ "id", "text", "about":
133
+ "face" | "self" }] }` in a place's hub block (or `true`: faces and options
134
+ only; ≤ 32 lines, ids `[a-z0-9-]{1,24}`, text ≤ 40). `hub.ballot(playerIds |
135
+ null, { title, text, until, mode: 'talk'|'vote'|'reveal', faces: [{ playerId,
136
+ note, off, votes, mark }], options: [{ id, text }], lines, feed: [{ from, to,
137
+ line }], picked } | null)` shows a phone bottom sheet of faces and chips
138
+ (per-player replaces shared; `null` for everyone clears all). Taps reach the
139
+ hook `ballot(hub, playerId, { face, line, option, mode })` as ids only,
140
+ checked against that player's card, three then one per 1.5 s. **No free
141
+ text**: never put a player's words in title/text/note/options; feed lines
142
+ are worded by the client from ids. The place keeps the feed and counts votes
143
+ (`picked` locks a vote in at once). Rule A: a card's version `v` moves only
144
+ when what can be tapped changes (mode, faces/off, lines, option ids,
145
+ picked), not on feed/text refreshes; a tap carries it and counts only on
146
+ the delivered, current version.
147
+ The card is drawn from who is here now: absent players' faces and feed rows
148
+ go, blocks among players here drop theirs and redact present names. Rule B:
149
+ without the key no ballot code runs, client or server (no `hub.ballot`).
150
+ - **Turning displays** (v1.55): `"HubSpin": { "rate": 45 }` (deg/s, ±720) on a
151
+ non-solid scene actor with no moving Body turns it on every client; no op.
59
152
  - **The HUD** is `{ title, big, text, timer: { since | until } }` in simulation
60
153
  ms (`hub.now`), drawn by the hub. It is the only way the game puts words on
61
154
  screen.
62
155
  - **Results** are server-only, once per player per visit, checked against
63
156
  `hub.result` in `castle.json`. No free text: the town writes the words. The
64
157
  `outcome` may be left out when a `score` says it all (a time trial).
158
+ - **A phone back within the reconnect window** (an app switch) is not arrived
159
+ again in a game unless the place sets `"resume": true` (v1.72): then `leave`
160
+ then `arrive` run again for the same player id, so the game must restore
161
+ that player's round state by account. One result per visit (a result
162
+ reported in `leave` is kept), one deadline, the end and first door kept.
65
163
  - **Players arrive at `hub.arrival.actor`**, in a row, facing
66
164
  `hub.arrival.face`, already placed when `arrive` runs. Never move the Player
67
165
  actor in the scene to change that -- change the arrival.
68
166
  - **Exit is always the hub's**: the Back control, `hub.end`, or
69
167
  `hub.maxDurationSec`. A game has no lobby and no leave button.
70
168
  - Never ship `blueprints/other-player.scene` or restyle the Player: every
71
- player is drawn as their avatar (`blueprints/avatar-<n>.scene` here).
169
+ player is drawn as their avatar (`blueprints/avatar-<n>.scene` here, sixteen
170
+ of them).
72
171
  - Controller: `"walk"` (the engine's `Player`) is the only preset; `hub.tune`
73
172
  scales one player's speed and jump within it. No
74
173
  player shove: other players are kinematic.
@@ -83,13 +182,47 @@ it is what every published hub game depends on.
83
182
  the button up through a moment at the reach, the cone or a shared owner --
84
183
  for places played on phones. `keepHeld: true` (contract v1.25) keeps a
85
184
  held object its holder's when another player stands nearer; without it the
86
- nearer player is handed it and the hold ends.
185
+ nearer player is handed it and the hold ends. In a scene with the engine's
186
+ orbit camera key (`"engine": { "camera": { "follow": "rigid", "control":
187
+ "orbit" } }`) a throw goes where the camera looks (PI - camAngle), not where
188
+ the character faces: the press turns the character that way
189
+ (`scene.faceRequest`), swings the held object round to the hold point along
190
+ it, and lets go once a movement report with the new facing has gone out
191
+ (150 ms at most without one; 2 s at most in all), so the server's
192
+ `hub.sim` facing is the throw's. The swing never puts the object more than
193
+ 0.5 m (straight line) from any position reported since the newest report
194
+ the server's body is sure to have reached (each as the report carried it:
195
+ the body where the hub left it, which the multiplayer kit packs straight
196
+ after, not the body a frame later once the client's physics, which runs
197
+ before the hub, has moved it on) -- acknowledged by multiplayer-3d
198
+ in a broadcast whose simulation time is past the ack's `tAck`, so a step ran
199
+ after it -- carry reports from before the press included. So neither
200
+ reports bunched by the network nor ticks that run no physics step can break
201
+ the owned-object move bound and take the object away mid-throw; half a turn
202
+ takes about a second on a good connection, and a swing the server cannot
203
+ confirm stalls and throws at the 2 s give-up from where it got. The default
204
+ (keyless) carry has no such bound: at the carry speed two of its reports
205
+ bunched into one tick can exceed the 0.6 m and lose the object (card
206
+ hub-game-grab-the-pickup-ease-in-1-2-m-3-m-hold). The swing adds no exposure
207
+ of its own: the carry before the press is that same carry, and the swing
208
+ never moves the object anywhere a report could fail (one the carry already
209
+ sent too far stalls it, and only a contact push in the client's physics,
210
+ which the carry shares, could move it further). The grab offer and the carry still follow
211
+ the character's facing. Without the key a throw is exactly what it was
212
+ (scripts/test-grab-orbit.mjs holds both).
87
213
  `hub.keepFor(actorId, playerId | null)` (contract v1.27) keeps a loose
88
214
  object for one player (a pillow of their own): nobody else is offered it or
89
215
  may grab it, and the `grab` hook is not asked about their tries. It ends
90
216
  with `null`, `hub.hide` and the player's leaving, and outlives `hub.reset`.
91
217
  It does not change who simulates the object, so its keeper is offered it
92
218
  only while nearest to it: put it beside them (`hub.reset(actorId, at)`).
219
+ - **Labels kept near** (contract v1.43): `"labels": "near"` in the `hub`
220
+ block, the deck's and the client's alone (like `tiers`). In a town the world
221
+ labels (`hub.label`'s plates, NPC lines and signs) are then kept near and
222
+ apart: a `"sign"` only within 12 m of the player (kept to 14 m), no two
223
+ overlapping, three at most (`code/client/labelsNear.js`, pure;
224
+ `scripts/test-labels.mjs`). Pointers, bubbles, emotes, marks and name tags
225
+ are not world labels. Without the key the hub system never calls it.
93
226
  - **A clear HUD** (contract v1.26): `"hud": { "clear": true }` in the `hub`
94
227
  block, for places played on phones. A big line with a text line under it
95
228
  is drawn at 32 px on one line (alone it keeps 56 px), labels, speech, marks
@@ -99,13 +232,148 @@ it is what every published hub game depends on.
99
232
  - **Idle play** (contract v1.6): `"idle": true` in the `hub` block (or
100
233
  `{ emotes, seats, sounds: ["sounds/x.mp3"] }`) gives players an emote picker
101
234
  (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
235
+ 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
236
  place's `hub.release` stands a sitter. Hooks `emote(hub, playerId, id)` and
104
237
  `sit(hub, playerId, seatId)` may refuse with `false`; `hub.emote(playerId,
105
238
  id)`, `hub.seat(playerId)`, and `hub.sound(actorId, file, { loop, volume,
106
239
  radius })` / `hub.sound(actorId, null)` for a listed sound file of the deck
107
240
  (carried in its content pack's `audio`, so a game behind a door sounds too;
108
241
  silent only on a town whose engine predates that).
242
+ - **The soundscape** (contract v1.42, v1.49, v1.50, v1.56, v1.60): `"soundscape": true` in the `hub`
243
+ block (or `{ babble, steps }`, each on unless `false`; the deck's, not a
244
+ place's) has the kit make its own sounds, synthesised in the client and
245
+ never a file or speech: NPC lines voiced as babble in each NPC's own voice
246
+ (from its actor id and name, or `HubNpc.voice: { type, pitch, rate, timbre }`),
247
+ footsteps under the player and those near them, and a speaker button (mute,
248
+ volume) that also sets the level of the place's `hub.sound` files. Client
249
+ only except explicit v1.50 `hub.cue` messages; without the key nothing of it
250
+ is made.
251
+ NPC babble uses all four original round-6 audition options, exported as
252
+ `VOICE_TYPES`: `townsfolk` (everyday, Rosenberg pulse, rate 3.3), `lively`
253
+ (excitable, same pulse, rate 4.6), `gruff` (older, LF Rd 1.2, rate 3.3,
254
+ formant gains [11,12,9,6]) and `gentle` (caring, Rosenberg, rate 3.3,
255
+ those lower formant gains, jitter 0.7/breath 0.75, jitter low-pass 120 Hz).
256
+ All use pitch 240, mouth 1.08, pace 1.3, breath low-pass 2400 Hz; source
257
+ gains 0.86/0.86/1.158/1.047 match the audition's voice RMS within 0.1%.
258
+ Valid `HubNpc.voice.type` wins; otherwise lower-case `${role} ${character}
259
+ ${name}` matches whole words in this fixed precedence (invalid types fall back):
260
+ - `gruff`: harbourmaster, harbour master, innkeeper, inn, fisher, captain,
261
+ smith, guard, elder, grandpa, old.
262
+ - `gentle`: nursery, clinic, nurse, nana, granny, gardener, healer, vet,
263
+ teacher, carer.
264
+ - `lively`: kid, child, barker, crier, hawker, postie, courier, runner,
265
+ coach, announcer, busker.
266
+ - Otherwise `townsfolk`; Innes does not match inn. Role is the place's own
267
+ key, character its characterBundle id, name its HubNpc name.
268
+ The actor/name hash keeps word seeds and per-NPC pitch
269
+ `240*2^(u*0.9-0.4)` (about 182–339 Hz), mouth rising with pitch (1–1.16),
270
+ and type rate ×0.9–1.1, with the same draws as before. Legacy
271
+ `HubNpc.voice.pitch` clamps to 80–500 Hz; `rate` clamps to 4–10 then maps
272
+ linearly to 2.5–6 (`7` → `4.25`); waveform `timbre` is accepted and ignored.
273
+ Complete words fit within 3 s including fade and 30 syllables. Each line
274
+ uses 22 synthesis nodes plus its distance gain, with per-context WeakMap
275
+ source/gate waves and noise. Breath puffs on the glottal open phase before
276
+ the formants; all three sources cut within 30 ms and every node releases
277
+ at natural end/failure. Scheduling origin is taken after construction.
278
+ `BABBLE_LEVEL` (~0.248) matches the old babble's median active RMS
279
+ (about −25.6 dBFS at volume 0.7), measured offline in Chromium.
280
+ Keyless/`babble: false` traces and market round-3 voices retain their
281
+ existing paths.
282
+ New fields alone opt into ambience and mapped steps: `zones` names a
283
+ bounds component (`x0,z0,x1,z1`); `ambience: { beds, default, spots, music }`
284
+ maps actor ids to `square`, `meadow`, `night`, `harbour`, `crowd` or `market`,
285
+ and spot component names to beds (nearest only, 4–14 m). The local player's
286
+ zone enters at the edge and stays until 0.75 m outside. Beds cross-fade
287
+ over 1.5 s, two at most plus one spot, sharing noise buffers; optional
288
+ quiet music uses fixed reusable voice pools per zone bed. Audible `hub.sound`
289
+ loops duck music to zero and ambience to 35%. Stadium, market (including
290
+ spots) and harbour beds render offline once per page context from the same
291
+ seeded generators into seamless 40/60/48 s loops, so phones play one buffer
292
+ instead of the live graph; music stays live. The original live generators
293
+ are the fallback when offline rendering is unavailable or fails. Referenced
294
+ heavy beds prewarm one at a time after activation while sound is allowed,
295
+ current zone first, with the same seeded plan scheduled up front and zero
296
+ offline suspends (v1.56). Object
297
+ `steps: { default, zones, paths }` maps surfaces (`street`, `grass`, `wood`,
298
+ `stone`, `sand`, `cobble`); path components carry `half`, `surface` and
299
+ `points` as `[x,z]` or `{x,z}`, and paths win over zones. Boolean steps
300
+ stay street everywhere; `true` creates no ambience, UI or action cues. Explicit `ui: true`
301
+ adds door departure (120 ms), settled arrival (320 ms), private town HUD
302
+ timer activity (180 ms) and chip tap (65 ms) cues on the UI bus. Two UI
303
+ voices and four starts per rolling second at most, two nodes per cue or
304
+ three for the whoosh, all released at the end; idle frames allocate none.
305
+ Only the departure tail may finish into a trip, without changing its
306
+ timing; hidden tab, mute or volume zero cuts even it. Arrival waits for
307
+ the first settled frame, at most 3 s. All other cues are dropped while
308
+ blocked. The first frame's private timer state is a baseline; shared/game
309
+ clocks and quiet changes make no activity cue. Holds do not distinguish
310
+ activities and token balances are only HUD text, so neither is parsed for
311
+ cues. No wire data is added. The hub passes chrome's optional `onChip`
312
+ callback only with UI enabled. All new sounds obey the first gesture,
313
+ two-frame settling gate and master volume. Validate with
314
+ `scripts/test-soundscape.mjs` and `test-manifest.mjs`.
315
+ v1.50 `cues: true` opts into `hub.cue({ player }, name)` or
316
+ `hub.cue({ actor, radius? }, name)` (default 12 m, 1–60): private delivery
317
+ or a distance-scaled broadcast, a six-token server budget per player or
318
+ shared for actors, false and warn once for invalid/off/rate-limited calls.
319
+ Closed names: kick, goal, cast, nibble, bite, catch, token, hat-bought,
320
+ hat-on, lantern, stamp, trial-start, trial-gate, trial-finish, pad-tick,
321
+ pad-go, court-chime, court-bell, court-splash, court-flutter, busker-jig,
322
+ busker-waltz. Court voices
323
+ are chime A at fixed stone 0, bell A (full 2.6 s), splash A and flutter B.
324
+ Chosen voices: kick A, catch C; other named audition voices as chosen.
325
+ Client state also voices wave B, dance C, cheer, bow, spin, sit
326
+ and private NPC panel opening; local full level, others within 12 m with
327
+ falloff and lower priority. Initial/quiet state is consumed silently.
328
+ Pads have only label text, so use explicit named cues, never text parsing.
329
+ Short cues and UI share two voices/four rolling starts per second on the UI bus;
330
+ the queue holds at most eight events, parts are built 75 ms ahead, and all
331
+ gates and cleanup apply. Cues alone adds no legacy UI callback or timer cue.
332
+ v1.60 busker names use `soundscapeBusker.js` on the UI bus, outside short
333
+ cue caps: actor sends every 10 s or less lease a loop for 25 s, within the
334
+ radius with linear falloff, actor present/not hidden and sound live. Only
335
+ the loudest loop plays; actor/name changes and departures fade in 0.3 s,
336
+ returning within the lease resumes. Private targets hear one full-gain pass.
337
+ Original 6/8 jig and 3/4 waltz phrases last 8–12 s with ten fixed nodes per
338
+ player, no per-note nodes, 0.3 s maximum lookahead and missed notes dropped.
339
+ Hide, scene change and teardown release all nodes; cues-off makes/drives no
340
+ busker layer. `BUSKER_LEVEL` targets −40 dBFS active RMS at volume 0.7,
341
+ pending Chromium calibration.
342
+ All six beds target about −33 dBFS active RMS at volume 0.7 (up 8 dB);
343
+ music is up 9 dB from its old −47 dBFS calibration target, sitting roughly
344
+ level with the beds, including stadium and the original market triangle tune.
345
+ Square A/B, Sunny A/B, Hollow warm/breathing pads, stadium Victory lap /
346
+ Arena bounce (126/132 BPM) and harbour Drift / Harbour jig (100 BPM waltz /
347
+ 76 dotted beats/min jig) alternate in seeded 3–5 minute runs ending on
348
+ bars, then 4–8 s silence. Hollow keeps its original D3 sine and a pad
349
+ 3 dB below it. Notes, timbres, envelopes and tempos are the auditions'.
350
+ Both song pools are made with the bed; frames create no music nodes.
351
+ Music nodes per song: square 37/42, sunny 37/27, Hollow pads 11/15 plus
352
+ two shared sine/envelope nodes, harbour 37/37, stadium 38/35.
353
+ Beds without/with music: square 7/87, meadow 7/72, night 7/36, harbour
354
+ 24/99, crowd 89/163, market 54/57; meadow/night may add a two-node call.
355
+ Harbour A-rolled has 22 generator nodes, including two 3.5 kHz wash
356
+ low-passes (Q 0) and 1.6 kHz foam high-passes; sea/gull/creak bypass the
357
+ wash roll-off. Both channels use identical gains. Random size stays
358
+ 0.6–1 for filter opening; body/foam amplitude uses
359
+ `0.6 + (size - 0.6) * 0.25` (0.6–0.7), without extra RNG draws.
360
+ `HARBOUR_WAVE_RMS` recalibrates the whole bed using a 300 s pure-JS
361
+ graph comparison to the previous bed. Whole-bed gain rises from
362
+ 0.316048 to 0.367716 (+1.315 dB), preserving model active RMS pending
363
+ a measured correction; the offline analysis is
364
+ `scripts/soundscape-wave-analysis.mjs` (called by the soundscape test).
365
+ Stadium crowd A keeps all 12 voices/eight clappers, 87 generator nodes.
366
+ Market Stalls A/Haggling B alternate in seeded 3–5 minute runs, draining
367
+ the last line before switching. Two 19-node Simlish pools retain pitches,
368
+ consonants, formants, pacing and envelopes; source phase continues between
369
+ lines. Three damped delays supply distance. Zone and spots share this
370
+ generator; a fallback spot adds 55 nodes at the existing 0.45 mix, no music.
371
+ All graphs, sources and delay loops release on fade/quiet/dispose; no
372
+ timers, real words or TTS. Stalled frames never replay missed lines.
373
+ Night's 4.1 kHz periodic cricket oscillator is removed;
374
+ wind/owl remain. `AMBIENCE_LEVELS` holds the levels. Footfall bodies have
375
+ 150–220 Hz high-pass filters; thumps are 40% lighter and decay in 55 ms,
376
+ including landings. The existing compressor stays on the opt-in master.
109
377
  - **Cabinets** (contract v1.7): a `HubDoor` with `"kind": "cabinet"` whose
110
378
  board from ghost carries `classic` is a door to a classic Castle deck the
111
379
  host plays itself. `hub.doors()` says `classic: true` once the board is
@@ -119,6 +387,12 @@ it is what every published hub game depends on.
119
387
  - `npm run check` bundles the deck and runs this kit's contract check; it must
120
388
  pass before `save-deck`, which runs the same check and refuses to publish.
121
389
 
390
+ - **Your games** (contract v1.54): deck-level `hub.yourGames: true` opts towns
391
+ into private hearted/recent rows and an arrival/return offer. The kit calls
392
+ `Hub.hearts()` once per signed-in town visit and `Hub.setHearts(doorIds)` on
393
+ a heart tap (at most eight, oldest first). No browser storage; no command or
394
+ new chrome in a deck without the key. `hub.results(playerId)` is unchanged.
395
+
122
396
  ## What is where
123
397
 
124
398
  | file | what it is |
@@ -129,26 +403,42 @@ it is what every published hub game depends on.
129
403
  | `code/server/actors.js` | `hub.move` and `hub.tint`: kinematic actors driven by the server, painted actors under a budget |
130
404
  | `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
405
  | `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 |
406
+ | `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` |
407
+ | `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 |
408
+ | `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 |
409
+ | `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 |
410
+ | `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 |
411
+ | `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 |
412
+ | `code/shared/cues.js`, `code/server/cues.js` | v1.50 closed cue names, private/actor delivery and server token buckets |
413
+ | `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 |
414
+ | `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 |
415
+ | `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
416
  | `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
417
  | `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 |
418
+ | `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
419
  | `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
420
  | `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
421
  | `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
422
  | `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` |
423
+ | `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` |
424
+ | `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 |
425
+ | `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
426
  | `code/server/manifest.js` | reads and checks the `hub` block and results (plain JS, shared with the check) |
140
427
  | `code/server/place.js` | which place a session runs, from the session alone |
141
428
  | `code/server/game.js` | the starter game (Flag Dash), copied into a new deck |
142
429
  | `code/client/hookLayer.js` | the client hooks, layered under the deck's by `castle.real-time` |
143
430
  | `code/systems/hub.js` | the door trip, Back, joining a friend's layer, the HUD, labels, hidden actors, holds, the ribbon |
144
431
  | `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 |
432
+ | `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
433
  | `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) |
434
+ | `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
435
  | `scripts/check.mjs` | the publish check (`onCheck`) |
149
436
  | `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
437
  | `code/client/pack.js`, `packFormat.js`, `sha256.js` | mounting a pack: fetch, verify, validate, build content |
151
438
  | `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 |
439
+ | `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 |
440
+ | `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) |
441
+ | `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
442
 
153
443
  ## Rules for editing this kit
154
444
 
@@ -169,3 +459,31 @@ describe themselves, and hub games are Castle-authored only until the door
169
459
  table and curation exist (HUB.md decision 10). `castle-web init --kit
170
460
  hub-game` works regardless. Adding the description is the switch that offers
171
461
  it.
462
+
463
+ Town performance opt-in: `hub.companionIdle: true` in the deck's `castle.json`
464
+ ticks a settled shoulder companion or waiting guide at 5 Hz and avoids unchanged appearance
465
+ and transform writes. Movement, speech, pose, visibility and reconnect changes
466
+ wake it on the next frame. Unset, companion updates run as before. The world
467
+ assembly enables this only with `COMPANION_IDLE=1 COMPANION=1`.
468
+
469
+ Town Low update opt-in: `hub.lowActorBudget: true` (`LOW_ACTOR_BUDGET=1` in
470
+ town assembly) budgets HubNpc/HubSpin behavior and model animation to 10 Hz
471
+ beyond 12 m of the player. Near actors, avatars and High keep full cadence.
472
+ Physics and event dispatch still run every frame. The client owns the optional
473
+ `actor.runtime.updateEvery` seconds and node `userData.animationEvery` seconds;
474
+ removing them restores the original cadence. No authored component is changed.
475
+
476
+ Town Low distance opt-in: `LOW_ACTOR_DISTANCE=1` writes
477
+ `hub.lowActorDistance: true` and positive `lowDrawDistance` metres beside an
478
+ authored actor's `id`. The town writes 18 m for NPCs and 24 m for fixed
479
+ scenery, preserving keep/Low-only actors and gameplay movers. Low checks
480
+ scenery bounds against the camera (NPCs use their origin), then detaches far
481
+ nodes and pauses their render synchronization. The live Transform is still
482
+ checked every 500 ms so actors return; High restores authored rendering.
483
+ Physics, network and collision remain active. Without the flag, metadata is
484
+ ignored and existing distances apply.
485
+
486
+ The Low budget also applies to the separate HubSpin controller, so distant
487
+ display rotations write at the chosen cadence. Restoring near/High cadence
488
+ flushes pending elapsed time. Model walk and authored motion share a tick
489
+ to preserve their composed pose between updates.
@@ -0,0 +1,28 @@
1
+ {
2
+ "name": "Avatar 11",
3
+ "actors": [
4
+ {
5
+ "components": {
6
+ "Transform": {
7
+ "y": 1
8
+ },
9
+ "Shape": {
10
+ "kind": "capsule",
11
+ "radius": 0.35,
12
+ "height": 1.4,
13
+ "color": "#7fc9b8",
14
+ "roughness": 0.4
15
+ },
16
+ "Body": {
17
+ "type": "kinematic",
18
+ "lockRotations": true
19
+ },
20
+ "Solid": {},
21
+ "Model": {
22
+ "file": "models/avatar-10.pxmodel",
23
+ "yOffset": -0.7
24
+ }
25
+ }
26
+ }
27
+ ]
28
+ }
@@ -0,0 +1,28 @@
1
+ {
2
+ "name": "Avatar 12",
3
+ "actors": [
4
+ {
5
+ "components": {
6
+ "Transform": {
7
+ "y": 1
8
+ },
9
+ "Shape": {
10
+ "kind": "capsule",
11
+ "radius": 0.35,
12
+ "height": 1.4,
13
+ "color": "#7fc9b8",
14
+ "roughness": 0.4
15
+ },
16
+ "Body": {
17
+ "type": "kinematic",
18
+ "lockRotations": true
19
+ },
20
+ "Solid": {},
21
+ "Model": {
22
+ "file": "models/avatar-11.pxmodel",
23
+ "yOffset": -0.7
24
+ }
25
+ }
26
+ }
27
+ ]
28
+ }