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
@@ -158,6 +158,11 @@ export type HubFriendsResult = {
158
158
  status: "unavailable";
159
159
  friends: null;
160
160
  };
161
+ /** Account-wide hub door hearts, in oldest-first order (at most eight). */
162
+ export interface HubHeartsResult {
163
+ status: "ok" | "unavailable";
164
+ hearts: string[];
165
+ }
161
166
  /** Hub.chat: only the messages after a cursor an earlier answer returned. */
162
167
  export interface HubChatParams {
163
168
  after?: string;
@@ -508,6 +513,7 @@ export interface CommandParams {
508
513
  "avatar.get": Record<string, never>;
509
514
  "avatar.set": {
510
515
  avatar: number;
516
+ color?: number;
511
517
  };
512
518
  "pass.offer": {
513
519
  passId: string;
@@ -530,6 +536,10 @@ export interface CommandParams {
530
536
  "hub.back": Record<string, never>;
531
537
  "hub.doors": Record<string, never>;
532
538
  "hub.friends": Record<string, never>;
539
+ "hub.hearts": Record<string, never>;
540
+ "hub.setHearts": {
541
+ doorIds: string[];
542
+ };
533
543
  "hub.jump": HubJumpParams;
534
544
  "hub.report": HubReportParams;
535
545
  "hub.chat": HubChatParams;
@@ -700,6 +710,8 @@ export interface CommandResult {
700
710
  "hub.back": HubBackResult;
701
711
  "hub.doors": HubDoorsResult;
702
712
  "hub.friends": HubFriendsResult;
713
+ "hub.hearts": HubHeartsResult;
714
+ "hub.setHearts": HubHeartsResult;
703
715
  "hub.jump": HubJumpResult;
704
716
  "hub.report": HubReportResult;
705
717
  "hub.chat": HubChatResult;
@@ -775,6 +787,8 @@ export interface UserPayload {
775
787
  color: string | null;
776
788
  }
777
789
  export interface AvatarResult {
790
+ /** Absent from a host before avatar colours. */
791
+ color?: number;
778
792
  status: "ok" | "unavailable";
779
793
  avatar: number | null;
780
794
  /** False while the player wears the default ghost gives every account. */
@@ -1,5 +1,5 @@
1
- import type { HubBackResult, HubCancelResult, HubChatResult, HubDoorsResult, HubFriendsResult, HubGoResult, HubJumpResult, HubReportResult, HubSayResult } from "./commands";
2
- export type { HubBackResult, HubCancelResult, HubCancelStatus, HubChatMessage, HubChatResult, HubDoor, HubDoorsResult, HubFriend, HubFriendsResult, HubGoParams, HubGoResult, HubHandoffResult, HubHandoffStatus, HubJumpResult, HubPlacementKind, HubReportResult, HubSayResult, } from "./commands";
1
+ import type { HubBackResult, HubCancelResult, HubChatResult, HubDoorsResult, HubFriendsResult, HubHeartsResult, HubGoResult, HubJumpResult, HubReportResult, HubSayResult } from "./commands";
2
+ export type { HubBackResult, HubCancelResult, HubCancelStatus, HubChatMessage, HubChatResult, HubDoor, HubDoorsResult, HubFriend, HubFriendsResult, HubHeartsResult, HubGoParams, HubGoResult, HubHandoffResult, HubHandoffStatus, HubJumpResult, HubPlacementKind, HubReportResult, HubSayResult, } from "./commands";
3
3
  /**
4
4
  * Doors between hub places. Every hub-kit deck is a place; ghost's door table
5
5
  * is the allowlist, and the host supplies real authentication and the current
@@ -35,6 +35,10 @@ export interface CastleHubApi {
35
35
  * on hosts without hub support.
36
36
  */
37
37
  friends(): Promise<HubFriendsResult>;
38
+ /** Read this signed-in account's hub door hearts. */
39
+ hearts(): Promise<HubHeartsResult>;
40
+ /** Replace the hearts, oldest first, at most eight distinct door ids. */
41
+ setHearts(doorIds: string[]): Promise<HubHeartsResult>;
38
42
  /**
39
43
  * Acquire the layer of this place a friend is in. The destination is this
40
44
  * same place in another session; join it exactly like a door's
@@ -5,6 +5,8 @@ export const Hub = {
5
5
  back,
6
6
  doors,
7
7
  friends,
8
+ hearts,
9
+ setHearts,
8
10
  jump,
9
11
  report,
10
12
  chat,
@@ -32,6 +34,17 @@ async function doors() {
32
34
  async function friends() {
33
35
  return hostRequest("hub.friends", {});
34
36
  }
37
+ async function hearts() {
38
+ return hostRequest("hub.hearts", {});
39
+ }
40
+ async function setHearts(doorIds) {
41
+ if (!Array.isArray(doorIds) || doorIds.length > 8 ||
42
+ doorIds.some((id) => typeof id !== "string" || !id.length || id.length > 64) ||
43
+ new Set(doorIds).size !== doorIds.length) {
44
+ throw new CastleError({ code: "INVALID_ARGUMENT", message: "Hub.setHearts requires at most eight distinct door ids.", operation: "Hub.setHearts" });
45
+ }
46
+ return hostRequest("hub.setHearts", { doorIds });
47
+ }
35
48
  async function jump(userId) {
36
49
  if (typeof userId !== "string" || userId.length === 0) {
37
50
  throw new CastleError({
@@ -7,6 +7,13 @@ const HELLO_TIMEOUT_MS = 10_000;
7
7
  const RECONNECT_BUDGET_MS = 30_000;
8
8
  const RECONNECT_DELAYS_MS = [500, 1_000, 2_000, 4_000, 8_000];
9
9
  const INVALID_DEV_RECONNECT_CLOSE_CODE = 4003;
10
+ // The play proxy closes a handshake it refuses with a reason (cauldron-game-server
11
+ // shared/src/constants.ts). The host that owns the session rejecting the credential is
12
+ // final. "Session ended" is ghost's routing verdict, which a host drain or a ghost
13
+ // error can also produce, so it takes two in a row before the session is given up on.
14
+ const PROXY_CREDENTIAL_REJECTED_CLOSE_CODE = 4401;
15
+ const PROXY_SESSION_ENDED_CLOSE_CODE = 4404;
16
+ const SESSION_ENDED_CONFIRMATIONS = 2;
10
17
  // The host may spend the full 15-second grant window waiting for author admission,
11
18
  // then up to 10 seconds on the fenced control-plane request. Keep the client above
12
19
  // that complete lifecycle so it cannot discard a valid durable receipt.
@@ -623,6 +630,7 @@ class MultiplayerConnectionImpl {
623
630
  async recover() {
624
631
  const startedAt = Date.now();
625
632
  let attempt = 0;
633
+ let sessionEndedCloses = 0;
626
634
  while (Date.now() - startedAt < RECONNECT_BUDGET_MS) {
627
635
  const delay = RECONNECT_DELAYS_MS[Math.min(attempt, RECONNECT_DELAYS_MS.length - 1)];
628
636
  attempt += 1;
@@ -633,7 +641,15 @@ class MultiplayerConnectionImpl {
633
641
  return;
634
642
  }
635
643
  catch (error) {
636
- if (error instanceof SocketClosedError && error.code === 1008)
644
+ const code = error instanceof SocketClosedError ? error.code : null;
645
+ if (code === 1008 || code === PROXY_CREDENTIAL_REJECTED_CLOSE_CODE)
646
+ break;
647
+ // Retrying a session that is gone only spends the budget; ask for a fresh join.
648
+ // Any other failure in between means the two refusals were not in a row.
649
+ sessionEndedCloses = code === PROXY_SESSION_ENDED_CLOSE_CODE
650
+ ? sessionEndedCloses + 1
651
+ : 0;
652
+ if (sessionEndedCloses >= SESSION_ENDED_CONFIRMATIONS)
637
653
  break;
638
654
  }
639
655
  }
@@ -60,7 +60,8 @@ const MAX_SUBJECT_BYTES = 256;
60
60
  const MAX_VALUE_BYTES = 256 * 1024;
61
61
  const encoder = new TextEncoder();
62
62
  const byteLength = (text) => encoder.encode(text).length;
63
- const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
63
+ // Unicode mode consumes valid pairs together; avoid lookbehind for Safari < 16.4.
64
+ const LONE_SURROGATE = /[\uD800-\uDFFF]/u;
64
65
  function invalid(message) {
65
66
  throw new SaveError({
66
67
  code: "CAULDRON_STORAGE_INVALID_ARGUMENT",
@@ -64,6 +64,52 @@ export interface MultiplayerHubWearReceipt {
64
64
  /** What the player now wears; null when cleared. */
65
65
  wearable: MultiplayerHubWearable | null;
66
66
  }
67
+ /** The classes of earned item a hub game may give (contract v1.53). */
68
+ export type MultiplayerHubEarnedClass = "badge" | "pin" | "belt" | "sash" | "held";
69
+ /** The home classes a hub game may give (contract v1.70/v1.73), never worn. */
70
+ export type MultiplayerHubHomeClass = "furniture" | "deed" | "pet";
71
+ /**
72
+ * An earned item: something a hub game gave a player for a stated deed, declared
73
+ * in that game's castle.json `hub.unlocks` and kept by Castle per account. It has
74
+ * no rarity. `deckId` is the game that declared it; `id` and `shape` match
75
+ * /^[a-z][a-z0-9-]{0,23}$/, `color` is '#rrggbb'.
76
+ */
77
+ export interface MultiplayerHubEarnedItem {
78
+ deckId: string;
79
+ id: string;
80
+ class: MultiplayerHubEarnedClass;
81
+ shape: string;
82
+ name: string;
83
+ deed: string;
84
+ color: string;
85
+ }
86
+ /** A furniture piece, area deed or adopted pet owned for the house, never shown on an avatar. */
87
+ export interface MultiplayerHubHomeItem {
88
+ deckId: string;
89
+ id: string;
90
+ class: MultiplayerHubHomeClass;
91
+ piece: string;
92
+ name: string;
93
+ deed: string;
94
+ color: string;
95
+ }
96
+ export interface MultiplayerHubUnlockReceipt {
97
+ unlocked: true;
98
+ /** True when this call gave the player the item for the first time. */
99
+ isNew: boolean;
100
+ /** What the player now shows in the earned slot (never a home item); null when none. */
101
+ earned: MultiplayerHubEarnedItem | null;
102
+ }
103
+ export interface MultiplayerHubWearEarnedReceipt {
104
+ /** What the player now shows in the earned slot; null when cleared. */
105
+ earned: MultiplayerHubEarnedItem | null;
106
+ }
107
+ export interface MultiplayerHubUnlocksRead {
108
+ /** Each player's owned wearable and home items, by user id. */
109
+ players: Record<string, {
110
+ owned: (MultiplayerHubEarnedItem | MultiplayerHubHomeItem)[];
111
+ }>;
112
+ }
67
113
  export interface MultiplayerHubPadUpdateInput {
68
114
  /** A pad door of this place, from ghost's door table. */
69
115
  doorId: string;
@@ -91,8 +137,12 @@ export interface MultiplayerHubPlayerResults {
91
137
  records: MultiplayerHubRecord[];
92
138
  /** The player's platform avatar, chosen or default; null when ghost has none to say. */
93
139
  avatar: number | null;
140
+ /** Account-wide door hearts, oldest first; absent on older ghosts. */
141
+ hearts?: string[];
94
142
  /** The player's wearable; null when none. Absent from a ghost older than wearables. */
95
143
  wearable?: MultiplayerHubWearable | null;
144
+ /** The earned item the player shows (contract v1.53); absent when none. */
145
+ earned?: MultiplayerHubEarnedItem;
96
146
  }
97
147
  export interface MultiplayerHubBoard {
98
148
  toDeckId: string;
@@ -134,6 +184,8 @@ export interface MultiplayerHubResultsRead {
134
184
  * and for a deck that declares no hub block.
135
185
  */
136
186
  export interface MultiplayerServerHub {
187
+ /** The owner user id, only in an owner door instance. */
188
+ readonly owner?: string;
137
189
  readonly place: string | null;
138
190
  readonly title: string | null;
139
191
  readonly result: MultiplayerHubResultShape | null;
@@ -156,6 +208,41 @@ export interface MultiplayerServerHub {
156
208
  * without it).
157
209
  */
158
210
  wear(playerId: string, wearable: MultiplayerHubWearable | null): Promise<MultiplayerHubWearReceipt>;
211
+ /**
212
+ * Gives a signed-in player one of this deck's declared earned items (castle.json
213
+ * `hub.unlocks`), by its id. Castle takes it only from a curated hub place, for a
214
+ * declared id; a first wearable unlock is also shown. Home items are never worn.
215
+ * Rejects with a `CAULDRON_HUB_*` code
216
+ * (`CAULDRON_HUB_UNAVAILABLE` on a runtime without it).
217
+ */
218
+ unlock(playerId: string, itemId: string): Promise<MultiplayerHubUnlockReceipt>;
219
+ /**
220
+ * Chooses which owned earned item a signed-in player shows, or none with null.
221
+ * Castle takes it only from the town; home items are refused.
222
+ * Rejects with a `CAULDRON_HUB_*` code
223
+ * (`CAULDRON_HUB_UNAVAILABLE` on a runtime without it).
224
+ */
225
+ wearEarned(playerId: string, earned: {
226
+ deckId: string;
227
+ id: string;
228
+ } | null): Promise<MultiplayerHubWearEarnedReceipt>;
229
+ /**
230
+ * The earned items players here own, by user id. Rejects with a `CAULDRON_HUB_*`
231
+ * code (`CAULDRON_HUB_UNAVAILABLE` on a runtime without it).
232
+ */
233
+ readUnlocks(userIds: readonly string[]): Promise<MultiplayerHubUnlocksRead>;
234
+ /** The connected player's friends among these candidates; platform refusals reject. */
235
+ friendsAmong(playerId: string, userIds: readonly string[]): Promise<string[]>;
236
+ /**
237
+ * The connected player's mutual friends and follows in either direction among
238
+ * these candidates, in one host read. Missing lists are empty; refusals reject.
239
+ * These relations belong to this player only; never send them to another client.
240
+ */
241
+ relationsAmong(playerId: string, userIds: readonly string[]): Promise<{
242
+ friends: string[];
243
+ follows: string[];
244
+ followedBy: string[];
245
+ }>;
159
246
  /**
160
247
  * Whether a block hides these two players from each other: either one blocked
161
248
  * the other, in either direction. Symmetric. The block lists themselves stay
@@ -39,6 +39,13 @@ function hubHiddenUserIds(raw) {
39
39
  }
40
40
  return ids.size > 0 ? ids : null;
41
41
  }
42
+ function unavailable(op, what) {
43
+ return new CastleError({
44
+ code: "CAULDRON_HUB_UNAVAILABLE",
45
+ message: `This host's runtime cannot ${what}.`,
46
+ operation: `session.hub.${op}`,
47
+ });
48
+ }
42
49
  export function createServerHub(platformHandle, arrivals, hiddenPair = () => false) {
43
50
  const pinned = platformHandle.hub;
44
51
  if (!pinned ||
@@ -69,12 +76,41 @@ export function createServerHub(platformHandle, arrivals, hiddenPair = () => fal
69
76
  place: typeof pinned.place === "string" ? pinned.place : null,
70
77
  title: typeof pinned.title === "string" ? pinned.title : null,
71
78
  result: pinned.result ?? null,
79
+ ...(typeof pinned.owner === "string" && pinned.owner.length > 0 ? { owner: pinned.owner } : {}),
72
80
  arrival(playerId) {
73
81
  return arrivals.get(playerId) ?? null;
74
82
  },
75
83
  hiddenPair(playerIdA, playerIdB) {
76
84
  return hiddenPair(playerIdA, playerIdB);
77
85
  },
86
+ async friendsAmong(playerId, userIds) {
87
+ const json = JSON.stringify({ playerId, userIds: [...userIds] });
88
+ const raw = typeof platformHandle.hubFriendsAmong === "function"
89
+ ? await platformHandle.hubFriendsAmong(json)
90
+ : await platformHandle.storage?.("hubFriendsAmong", json);
91
+ const answer = JSON.parse(raw ?? "null");
92
+ return Array.isArray(answer?.userIds) ? answer.userIds : [];
93
+ },
94
+ async relationsAmong(playerId, userIds) {
95
+ const asked = new Set(userIds);
96
+ const json = JSON.stringify({ playerId, userIds: [...userIds] });
97
+ let raw;
98
+ if (typeof platformHandle.hubFriendsAmong === "function") {
99
+ raw = await platformHandle.hubFriendsAmong(json);
100
+ }
101
+ else {
102
+ raw = await platformHandle.storage?.("hubFriendsAmong", json);
103
+ }
104
+ const answer = JSON.parse(raw ?? "null");
105
+ const list = (value) => Array.isArray(value)
106
+ ? value.filter((id) => typeof id === "string" && asked.has(id))
107
+ : [];
108
+ return {
109
+ friends: list(answer?.userIds),
110
+ follows: list(answer?.follows),
111
+ followedBy: list(answer?.followedBy),
112
+ };
113
+ },
78
114
  async reportResult(playerId, result) {
79
115
  const { place, outcome, score, stats } = result ?? {};
80
116
  return (await call("hubResult", {
@@ -121,5 +157,39 @@ export function createServerHub(platformHandle, arrivals, hiddenPair = () => fal
121
157
  wearable: (receipt.wearable ?? null),
122
158
  };
123
159
  },
160
+ async unlock(playerId, itemId) {
161
+ if (typeof platformHandle.hubUnlock !== "function") {
162
+ throw unavailable("hubUnlock", "give earned items");
163
+ }
164
+ const receipt = await call("hubUnlock", { playerId, itemId });
165
+ return {
166
+ unlocked: true,
167
+ isNew: receipt.isNew === true,
168
+ earned: (receipt.earned ?? null),
169
+ };
170
+ },
171
+ async wearEarned(playerId, earned) {
172
+ if (typeof platformHandle.hubWearEarned !== "function") {
173
+ throw unavailable("hubWearEarned", "choose earned items");
174
+ }
175
+ const receipt = await call("hubWearEarned", {
176
+ playerId,
177
+ earned: earned === null || earned === undefined
178
+ ? null
179
+ : { deckId: earned.deckId, id: earned.id },
180
+ });
181
+ return {
182
+ earned: (receipt.earned ?? null),
183
+ };
184
+ },
185
+ async readUnlocks(userIds) {
186
+ if (typeof platformHandle.hubUnlocksRead !== "function") {
187
+ throw unavailable("hubUnlocksRead", "read earned items");
188
+ }
189
+ const read = await call("hubUnlocksRead", { userIds: [...(userIds ?? [])] });
190
+ return {
191
+ players: (read.players ?? {}),
192
+ };
193
+ },
124
194
  });
125
195
  }
@@ -53,6 +53,7 @@ export interface PlatformHandle {
53
53
  on(event: "worldCharacterTurn", callback: (request: PlatformWorldCharacterTurn) => unknown): void;
54
54
  on(event: "worldCharacterCommand", callback: (request: PlatformWorldCharacterCommand) => unknown): void;
55
55
  on(event: "worldCharacterRead", callback: (request: PlatformWorldCharacterRead) => unknown): void;
56
+ on(event: "worldCharacterTool", callback: (request: PlatformWorldCharacterTool) => unknown): void;
56
57
  /**
57
58
  * Deck storage. Strings in and strings out, like the rest of this handle, so a
58
59
  * runtime other than the Node shim can implement it without knowing what storage is.
@@ -68,12 +69,18 @@ export interface PlatformHandle {
68
69
  /** Persistent-world checkpoint broker. The host stamps the hidden world binding. */
69
70
  worldCheckpointRead?(): Promise<string>;
70
71
  worldCheckpointCommit?(argsJson: string): Promise<string>;
71
- worldCharacterSend?(grantId: string): Promise<string>;
72
+ /** `tools` is the turn's place tools, passed only when non-empty. */
73
+ worldCharacterSend?(grantId: string, tools?: readonly PlatformPlaceTool[]): Promise<string>;
72
74
  worldCharacterCommand?(grantId: string): Promise<string>;
73
75
  worldCharacterRead?(grantId: string): Promise<string>;
74
76
  worldCharacterRuntimeCreate?(argsJson: string): Promise<string>;
75
77
  worldCharacterRuntimeList?(): Promise<string>;
76
78
  worldCharacterReject?(grantId: string, code?: string): void;
79
+ /**
80
+ * Answers a `worldCharacterTool` event with at most 1 KiB of UTF-8. Present only
81
+ * when the host serves place tools, which is also what lets a send declare them.
82
+ */
83
+ worldCharacterToolResult?(requestId: string, result: string): Promise<string>;
77
84
  /**
78
85
  * The hub place this session runs, as ghost pinned it from the published
79
86
  * castle.json `hub` block. Present only when the host services the hub ops
@@ -83,8 +90,16 @@ export interface PlatformHandle {
83
90
  hubResult?(argsJson: string): Promise<string>;
84
91
  hubPadUpdate?(argsJson: string): Promise<string>;
85
92
  hubResultsRead?(argsJson: string): Promise<string>;
93
+ /** Friends among candidates (hub contract v1.36); older images use storage. */
94
+ hubFriendsAmong?(argsJson: string): Promise<string>;
86
95
  /** Absent on a runtime older than wearables (contract v1.4). */
87
96
  hubWear?(argsJson: string): Promise<string>;
97
+ /** Absent on a runtime older than earned items (contract v1.53). */
98
+ hubUnlock?(argsJson: string): Promise<string>;
99
+ /** Absent on a runtime older than earned items (contract v1.53). */
100
+ hubWearEarned?(argsJson: string): Promise<string>;
101
+ /** Absent on a runtime older than earned items (contract v1.53). */
102
+ hubUnlocksRead?(argsJson: string): Promise<string>;
88
103
  readonly config: PlatformSessionConfig;
89
104
  }
90
105
  export interface PlatformHubResultShape {
@@ -98,6 +113,7 @@ export interface PlatformHubResultShape {
98
113
  stats: Record<string, "number" | "string">;
99
114
  }
100
115
  export interface PlatformHubPlace {
116
+ owner?: string;
101
117
  place?: string;
102
118
  title?: string | null;
103
119
  result?: PlatformHubResultShape | null;
@@ -124,6 +140,20 @@ export interface PlatformWorldCharacterRead {
124
140
  };
125
141
  query: unknown;
126
142
  }
143
+ /** A lookup a place declares for one character turn. */
144
+ export interface PlatformPlaceTool {
145
+ name: string;
146
+ description: string;
147
+ input_schema: Record<string, unknown>;
148
+ }
149
+ export interface PlatformWorldCharacterTool {
150
+ requestId: string;
151
+ operationId: string;
152
+ characterId: string;
153
+ playerId: string;
154
+ name: string;
155
+ input: Record<string, unknown>;
156
+ }
127
157
  export interface PlatformWorldCharacterTurn {
128
158
  grantId: string;
129
159
  requestId: string;
@@ -23,6 +23,12 @@ export interface ServerStorageScope extends SaveBucketApi {
23
23
  increment(key: string, delta?: number): Promise<number>;
24
24
  list<T extends Json = Json>(options?: ServerStorageListOptions): Promise<ServerStorageListPage<T>>;
25
25
  }
26
+ export interface ServerTownStorage {
27
+ get<T extends Json = Json>(keys: string[]): Promise<Record<string, T>>;
28
+ set(values: Record<string, Json>): Promise<void>;
29
+ remove(keys: string[]): Promise<void>;
30
+ increment(key: string, delta?: number): Promise<number>;
31
+ }
26
32
  export interface ServerStorageBoardScore {
27
33
  subject: string;
28
34
  score: number;
@@ -263,6 +269,13 @@ export interface ServerStorage extends SaveApi {
263
269
  readonly deck: ServerStorageScope;
264
270
  /** One player's public data. Readable by anyone; writable by them or by this server. */
265
271
  user(userId: string): ServerStorageScope;
272
+ /**
273
+ * The door deck's source town's deck-scope rows, for one player in this session.
274
+ * Only a door deck's server may call it; a town gets CAULDRON_HUB_NO_TOWN.
275
+ * In an owner house, only the owner's rows are accessible. Quota counts against
276
+ * the town. Each key must be tokens|spent|own|hat|chirp, then userId, as its first two segments.
277
+ */
278
+ town(userId: string): ServerTownStorage;
266
279
  board(name: string): ServerStorageBoard;
267
280
  /** Opens one player's experimental, generation-bound game namespace. */
268
281
  playthrough(userId: string): Promise<ServerPlaythrough>;
@@ -91,6 +91,9 @@ export function createServerStorage(platformHandle) {
91
91
  }
92
92
  return createScope(call, "USER", userId, saveApi);
93
93
  },
94
+ town(userId) {
95
+ return createTownStorage(call, userId);
96
+ },
94
97
  board(name) {
95
98
  return createBoard(call, name);
96
99
  },
@@ -243,6 +246,49 @@ function createPlaythrough(call, subject, generation) {
243
246
  },
244
247
  });
245
248
  }
249
+ /** The town's per-player namespaces a door deck may reach; ghost holds the same list. */
250
+ const TOWN_PLAYER_NAMESPACES = ["tokens", "spent", "own", "hat", "chirp"];
251
+ function createTownStorage(call, subject) {
252
+ const args = { scope: "DECK", subject, place: "town" };
253
+ // Validate in the async verbs, so a bad subject poisons the handle without
254
+ // throwing when the author creates it. Validate every key before any chunk lands.
255
+ const keysFor = (keys, operation) => {
256
+ assertUserId(subject, operation);
257
+ const checked = assertKeys(keys, operation);
258
+ for (const key of checked) {
259
+ const segments = key.split(":");
260
+ if (!TOWN_PLAYER_NAMESPACES.includes(segments[0]) || segments[1] !== subject) {
261
+ throw storageError("CAULDRON_STORAGE_INVALID_ARGUMENT", `Town storage key ${JSON.stringify(key)} must be ${TOWN_PLAYER_NAMESPACES.join("|")}:${subject}[:...].`, operation);
262
+ }
263
+ }
264
+ return checked;
265
+ };
266
+ return {
267
+ async get(keys) {
268
+ const entries = [];
269
+ for (const chunk of chunked(keysFor(keys, "session.storage.town.get"), MAX_KEYS_PER_CALL)) {
270
+ entries.push(...await call("get", { ...args, keys: chunk }));
271
+ }
272
+ return decodeEntries(entries, "session.storage.town.get");
273
+ },
274
+ async set(values) {
275
+ keysFor(Object.keys(values), "session.storage.town.set");
276
+ const entries = encodeEntries(values, "session.storage.town.set");
277
+ for (const chunk of batched(entries, "session.storage.town.set")) {
278
+ await call("set", { ...args, entries: chunk });
279
+ }
280
+ },
281
+ async remove(keys) {
282
+ for (const chunk of chunked(keysFor(keys, "session.storage.town.remove"), MAX_KEYS_PER_CALL)) {
283
+ await call("delete", { ...args, keys: chunk });
284
+ }
285
+ },
286
+ async increment(key, delta = 1) {
287
+ keysFor([key], "session.storage.town.increment");
288
+ return Number(await call("increment", { ...args, key, delta }));
289
+ },
290
+ };
291
+ }
246
292
  function createScope(call, scope, subject, saveApi) {
247
293
  return {
248
294
  ...createSaveBucket(saveApi, scope === "DECK" ? "deck" : "user", subject ?? undefined),
@@ -1,4 +1,4 @@
1
- import type { MultiplayerSessionMode, PlatformHandle, PlayerIdentity } from "./platformHandle";
1
+ import type { MultiplayerSessionMode, PlatformHandle, PlatformPlaceTool, PlayerIdentity } from "./platformHandle";
2
2
  import type { Json } from "../types";
3
3
  import type { MultiplayerWorldCharacterCommand, MultiplayerWorldCharacterCommandResult, MultiplayerWorldCharacterCommandResultValue } from "../multiplayer";
4
4
  import { type ServerStorage } from "./storage";
@@ -8,8 +8,8 @@ export { createSaveCoordinator } from "../saveCoordinator";
8
8
  export type { CoordinatedChange, CoordinatedSave, SaveCoordinator, SaveStatus, } from "../saveCoordinator";
9
9
  export { SaveError } from "../save";
10
10
  export type { SaveApi, SaveBucketApi, SaveBucketRead, SaveChange, SaveCheck, SaveClaimed, SaveClaimInput, SaveErrorEnvelope, SaveInitial, SaveInitializeInput, SaveOpened, SaveOperation, SaveReadTarget, SaveReceipt, SaveRevision, SaveRows, SaveScope, SaveSelection, SaveSnapshot, SaveTarget, SaveTransactionInput, SaveWriter, } from "../save";
11
- export type { MultiplayerHubArrival, MultiplayerHubBoard, MultiplayerHubOutcome, MultiplayerHubPadUpdateInput, MultiplayerHubPadUpdateResult, MultiplayerHubPlayerResults, MultiplayerHubRecord, MultiplayerHubReportReceipt, MultiplayerHubResultInput, MultiplayerHubResultRow, MultiplayerHubResultShape, MultiplayerHubResultsRead, MultiplayerHubResultsReadInput, MultiplayerHubWearable, MultiplayerHubWearReceipt, MultiplayerServerHub, } from "./hub";
12
- export type { CharacterActionNotice, CharacterGameStateOperation, CharacterGameStateResult, CharacterKnowledgeDeliveryOperation, CharacterKnowledgeDeliveryResult, CharacterKnowledgeSource, CompleteCharacterBeatInput, DeliverCharacterKnowledgeInput, RecordCharacterEventInput, SetCharacterGameStateInput, ShareCharacterClaimInput, ServerStorage, ServerStorageBoard, ServerStorageBoardScore, ServerStorageListEntry, ServerStorageListOptions, ServerStorageListPage, ServerPlaythrough, ServerPlaythroughCharacters, ServerCharacterHistoryOptions, ServerStorageScope, } from "./storage";
11
+ export type { MultiplayerHubArrival, MultiplayerHubBoard, MultiplayerHubOutcome, MultiplayerHubPadUpdateInput, MultiplayerHubPadUpdateResult, MultiplayerHubPlayerResults, MultiplayerHubRecord, MultiplayerHubReportReceipt, MultiplayerHubResultInput, MultiplayerHubResultRow, MultiplayerHubResultShape, MultiplayerHubResultsRead, MultiplayerHubResultsReadInput, MultiplayerHubWearable, MultiplayerHubWearReceipt, MultiplayerHubEarnedClass, MultiplayerHubEarnedItem, MultiplayerHubHomeClass, MultiplayerHubHomeItem, MultiplayerHubUnlockReceipt, MultiplayerHubUnlocksRead, MultiplayerHubWearEarnedReceipt, MultiplayerServerHub, } from "./hub";
12
+ export type { CharacterActionNotice, CharacterGameStateOperation, CharacterGameStateResult, CharacterKnowledgeDeliveryOperation, CharacterKnowledgeDeliveryResult, CharacterKnowledgeSource, CompleteCharacterBeatInput, DeliverCharacterKnowledgeInput, RecordCharacterEventInput, SetCharacterGameStateInput, ShareCharacterClaimInput, ServerStorage, ServerStorageBoard, ServerStorageBoardScore, ServerStorageListEntry, ServerStorageListOptions, ServerStorageListPage, ServerPlaythrough, ServerPlaythroughCharacters, ServerCharacterHistoryOptions, ServerStorageScope, ServerTownStorage, } from "./storage";
13
13
  export interface MultiplayerServerPlayer extends PlayerIdentity {
14
14
  playerId: string;
15
15
  readonly participantId: string;
@@ -268,11 +268,35 @@ export interface MultiplayerWorldCharacterTurn {
268
268
  readonly players: readonly MultiplayerServerPlayer[];
269
269
  readonly characterIds: readonly string[];
270
270
  };
271
- /** Durably admits the exact host-authorized request. No arguments can broaden it. */
272
- send(): Promise<MultiplayerWorldCharacterAdmission>;
271
+ /**
272
+ * Durably admits the exact host-authorized request. No arguments can broaden it:
273
+ * `tools` only declares lookups the character may make of this place during the
274
+ * turn (answered by `onWorldCharacterTool`), and is dropped on a host that does
275
+ * not serve place tools.
276
+ */
277
+ send(options?: MultiplayerWorldCharacterSendOptions): Promise<MultiplayerWorldCharacterAdmission>;
273
278
  /** Explicitly rejects the request before admission. */
274
279
  reject(code?: string): void;
275
280
  }
281
+ /**
282
+ * A lookup a place offers its character for one turn. The host drops an invalid
283
+ * list whole (the turn proceeds without tools): at most 8, a unique `name` matching
284
+ * `^[A-Za-z][A-Za-z0-9_]{0,31}$` other than `perform_action` or `capture_claim`,
285
+ * a 1..300 character `description`, and a JSON-object `input_schema` of at most
286
+ * 1 KiB, with the whole list at most 6 KiB.
287
+ */
288
+ export type MultiplayerPlaceTool = PlatformPlaceTool;
289
+ export interface MultiplayerWorldCharacterSendOptions {
290
+ tools?: readonly MultiplayerPlaceTool[];
291
+ }
292
+ /** One place-tool use by a character during a turn this place admitted. */
293
+ export interface MultiplayerWorldCharacterToolRequest {
294
+ readonly operationId: string;
295
+ readonly characterId: string;
296
+ readonly playerId: string;
297
+ readonly name: string;
298
+ readonly input: Readonly<Record<string, unknown>>;
299
+ }
276
300
  type CallbackResult = unknown;
277
301
  export interface MultiplayerServerCallbacks {
278
302
  onStart?: (session: MultiplayerServerSession) => CallbackResult;
@@ -284,6 +308,13 @@ export interface MultiplayerServerCallbacks {
284
308
  onWorldCharacterTurn?: (session: MultiplayerServerSession, turn: MultiplayerWorldCharacterTurn) => CallbackResult;
285
309
  onWorldCharacterCommand?: (session: MultiplayerServerSession, request: MultiplayerWorldCharacterCommandRequest) => CallbackResult;
286
310
  onWorldCharacterRead?: (session: MultiplayerServerSession, request: MultiplayerWorldCharacterReadRequest) => CallbackResult;
311
+ /**
312
+ * Answers a place-tool use declared through `turn.send({ tools })`. Return a
313
+ * string or a JSON value (stringified); a result over 1 KiB becomes
314
+ * `{"error":"result too large"}` and a throw `{"error":"tool failed"}`. The host
315
+ * waits 1.5 s, then the character answers without it.
316
+ */
317
+ onWorldCharacterTool?: (request: MultiplayerWorldCharacterToolRequest, session: MultiplayerServerSession) => unknown;
287
318
  onTick?: (session: MultiplayerServerSession) => CallbackResult;
288
319
  onReplaced?: (session: MultiplayerServerSession) => CallbackResult;
289
320
  /**