castle-web-cli 0.4.232 → 0.4.234

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (587) hide show
  1. package/dist/agent-failures.d.ts +8 -0
  2. package/dist/agent-failures.js +19 -2
  3. package/dist/agent-prompts.d.ts +1 -1
  4. package/dist/agent-prompts.js +10 -3
  5. package/dist/agent.d.ts +64 -3
  6. package/dist/agent.js +170 -81
  7. package/dist/api.d.ts +11 -0
  8. package/dist/api.js +43 -0
  9. package/dist/bundle.d.ts +64 -0
  10. package/dist/bundle.js +558 -2
  11. package/dist/castle-host/host.d.ts +18 -2
  12. package/dist/castle-host/host.js +844 -39
  13. package/dist/castleJson.d.ts +23 -2
  14. package/dist/castleJson.js +46 -2
  15. package/dist/check.d.ts +3 -1
  16. package/dist/check.js +20 -3
  17. package/dist/chunkLoader.d.ts +3 -0
  18. package/dist/chunkLoader.js +111 -0
  19. package/dist/devParty.d.ts +26 -0
  20. package/dist/devParty.js +231 -0
  21. package/dist/devSaveStorage.js +4 -0
  22. package/dist/devSessionStorage.js +50 -2
  23. package/dist/devSocial.d.ts +24 -0
  24. package/dist/devSocial.js +70 -0
  25. package/dist/ide.d.ts +2 -0
  26. package/dist/ide.js +119 -15
  27. package/dist/importPinMismatch.d.ts +22 -0
  28. package/dist/importPinMismatch.js +77 -0
  29. package/dist/importRegression.js +3 -15
  30. package/dist/imports.d.ts +10 -3
  31. package/dist/imports.js +88 -20
  32. package/dist/index.js +11 -4
  33. package/dist/init.js +1 -1
  34. package/dist/platformDoc.js +22 -0
  35. package/dist/routerFences.d.ts +5 -0
  36. package/dist/routerFences.js +12 -2
  37. package/dist/save-deck.d.ts +25 -1
  38. package/dist/save-deck.js +178 -9
  39. package/dist/serve.js +32 -11
  40. package/dist/shell/assets/{index-D2tWM896.js → index-DulbYIJm.js} +97 -97
  41. package/dist/shell/assets/index-MVLfNYd9.css +1 -0
  42. package/dist/shell/index.html +2 -2
  43. package/dist/taskSteer.d.ts +13 -0
  44. package/dist/taskSteer.js +22 -2
  45. package/dist/vitePlugins.d.ts +2 -1
  46. package/dist/vitePlugins.js +13 -0
  47. package/kits/base/castle.json +1 -1
  48. package/kits/base/package-lock.json +1 -1
  49. package/kits/base/sdk/README.md +339 -5
  50. package/kits/base/sdk/avatar.d.ts +6 -2
  51. package/kits/base/sdk/avatar.js +12 -4
  52. package/kits/base/sdk/castle.d.ts +7 -3
  53. package/kits/base/sdk/castle.js +2 -0
  54. package/kits/base/sdk/commands.d.ts +176 -1
  55. package/kits/base/sdk/commands.js +3 -0
  56. package/kits/base/sdk/display.d.ts +3 -0
  57. package/kits/base/sdk/display.js +9 -3
  58. package/kits/base/sdk/hub.d.ts +37 -6
  59. package/kits/base/sdk/hub.js +63 -4
  60. package/kits/base/sdk/multiplayer.d.ts +7 -1
  61. package/kits/base/sdk/multiplayer.js +148 -32
  62. package/kits/base/sdk/multiplayerProtocol.d.ts +2 -0
  63. package/kits/base/sdk/party.d.ts +23 -0
  64. package/kits/base/sdk/party.js +91 -0
  65. package/kits/base/sdk/reconnectBudget.d.ts +23 -0
  66. package/kits/base/sdk/reconnectBudget.js +96 -0
  67. package/kits/base/sdk/save.d.ts +38 -1
  68. package/kits/base/sdk/save.js +81 -7
  69. package/kits/base/sdk/server/hub.d.ts +117 -0
  70. package/kits/base/sdk/server/hub.js +119 -2
  71. package/kits/base/sdk/server/platformHandle.d.ts +43 -1
  72. package/kits/base/sdk/server/storage.d.ts +17 -0
  73. package/kits/base/sdk/server/storage.js +65 -3
  74. package/kits/base/sdk/server/wrapper.d.ts +43 -6
  75. package/kits/base/sdk/server/wrapper.js +93 -9
  76. package/kits/base/sdk/social.d.ts +9 -0
  77. package/kits/base/sdk/social.js +5 -0
  78. package/kits/hub-game/CLAUDE.md +451 -13
  79. package/kits/hub-game/README.md +63 -0
  80. package/kits/hub-game/blueprints/avatar-10.scene +28 -0
  81. package/kits/hub-game/blueprints/avatar-11.scene +28 -0
  82. package/kits/hub-game/blueprints/avatar-12.scene +28 -0
  83. package/kits/hub-game/blueprints/avatar-13.scene +28 -0
  84. package/kits/hub-game/blueprints/avatar-14.scene +28 -0
  85. package/kits/hub-game/blueprints/avatar-15.scene +28 -0
  86. package/kits/hub-game/blueprints/avatar-4.scene +28 -0
  87. package/kits/hub-game/blueprints/avatar-5.scene +28 -0
  88. package/kits/hub-game/blueprints/avatar-6.scene +28 -0
  89. package/kits/hub-game/blueprints/avatar-7.scene +28 -0
  90. package/kits/hub-game/blueprints/avatar-8.scene +28 -0
  91. package/kits/hub-game/blueprints/avatar-9.scene +28 -0
  92. package/kits/hub-game/castle.json +5 -5
  93. package/kits/hub-game/code/client/act.js +312 -0
  94. package/kits/hub-game/code/client/actionLayout.js +147 -0
  95. package/kits/hub-game/code/client/actionOverflow.js +556 -0
  96. package/kits/hub-game/code/client/actorBudget.js +47 -0
  97. package/kits/hub-game/code/client/arrivalCamera.js +50 -0
  98. package/kits/hub-game/code/client/askSlot.js +117 -0
  99. package/kits/hub-game/code/client/attention.js +11 -2
  100. package/kits/hub-game/code/client/avatar.js +311 -35
  101. package/kits/hub-game/code/client/avatarCap.js +228 -0
  102. package/kits/hub-game/code/client/avatarColors.js +70 -0
  103. package/kits/hub-game/code/client/avatarFaces.js +21 -0
  104. package/kits/hub-game/code/client/avatarShare.js +253 -0
  105. package/kits/hub-game/code/client/backVisibility.js +13 -0
  106. package/kits/hub-game/code/client/ballot.js +472 -0
  107. package/kits/hub-game/code/client/build.js +38 -0
  108. package/kits/hub-game/code/client/chat.js +41 -5
  109. package/kits/hub-game/code/client/chatModeration.js +5 -0
  110. package/kits/hub-game/code/client/chrome.js +2144 -160
  111. package/kits/hub-game/code/client/companion.js +716 -0
  112. package/kits/hub-game/code/client/companionDress.js +99 -0
  113. package/kits/hub-game/code/client/crowdNames.js +241 -0
  114. package/kits/hub-game/code/client/decor.js +515 -0
  115. package/kits/hub-game/code/client/defaultEnvironment.js +194 -0
  116. package/kits/hub-game/code/client/doorErrors.js +39 -0
  117. package/kits/hub-game/code/client/earned.js +131 -0
  118. package/kits/hub-game/code/client/emoteBubble.js +75 -0
  119. package/kits/hub-game/code/client/fall.js +18 -0
  120. package/kits/hub-game/code/client/farAvatars.js +233 -0
  121. package/kits/hub-game/code/client/firstJoin.js +9 -2
  122. package/kits/hub-game/code/client/fpsTelemetry.js +50 -0
  123. package/kits/hub-game/code/client/frameBatch.js +5 -0
  124. package/kits/hub-game/code/client/grab.js +368 -29
  125. package/kits/hub-game/code/client/hookLayer.js +385 -20
  126. package/kits/hub-game/code/client/hudCopy.js +51 -0
  127. package/kits/hub-game/code/client/hudRate.js +20 -0
  128. package/kits/hub-game/code/client/idle.js +177 -24
  129. package/kits/hub-game/code/client/interestCap.js +81 -0
  130. package/kits/hub-game/code/client/invites.js +231 -0
  131. package/kits/hub-game/code/client/joinError.js +9 -0
  132. package/kits/hub-game/code/client/keys.js +36 -0
  133. package/kits/hub-game/code/client/labelsNear.js +234 -0
  134. package/kits/hub-game/code/client/landscapeLayout.js +17 -0
  135. package/kits/hub-game/code/client/layoutCache.js +264 -0
  136. package/kits/hub-game/code/client/loadTelemetry.js +20 -0
  137. package/kits/hub-game/code/client/loadingCover.js +148 -0
  138. package/kits/hub-game/code/client/loadingEntry.js +8 -0
  139. package/kits/hub-game/code/client/menuIcons.js +34 -0
  140. package/kits/hub-game/code/client/menuRows.js +43 -0
  141. package/kits/hub-game/code/client/modelReady.js +7 -0
  142. package/kits/hub-game/code/client/pack.js +6 -2
  143. package/kits/hub-game/code/client/packFormat.js +3 -3
  144. package/kits/hub-game/code/client/padCueArrival.js +23 -0
  145. package/kits/hub-game/code/client/padCues.js +112 -0
  146. package/kits/hub-game/code/client/padOccupancy.js +88 -0
  147. package/kits/hub-game/code/client/padReadability.js +26 -0
  148. package/kits/hub-game/code/client/padRings.js +69 -0
  149. package/kits/hub-game/code/client/pushVisit.js +14 -0
  150. package/kits/hub-game/code/client/quality.js +205 -0
  151. package/kits/hub-game/code/client/qualityEntry.js +55 -0
  152. package/kits/hub-game/code/client/rehello.js +167 -0
  153. package/kits/hub-game/code/client/safeLayout.js +338 -0
  154. package/kits/hub-game/code/client/safeStyle.js +42 -0
  155. package/kits/hub-game/code/client/say.js +12 -3
  156. package/kits/hub-game/code/client/shot.js +146 -0
  157. package/kits/hub-game/code/client/shotFit.js +56 -0
  158. package/kits/hub-game/code/client/signIn.js +28 -0
  159. package/kits/hub-game/code/client/sound.js +63 -8
  160. package/kits/hub-game/code/client/soundscape.js +1151 -0
  161. package/kits/hub-game/code/client/soundscapeActions.js +99 -0
  162. package/kits/hub-game/code/client/soundscapeAmbience.js +453 -0
  163. package/kits/hub-game/code/client/soundscapeBaked.js +143 -0
  164. package/kits/hub-game/code/client/soundscapeBusker.js +217 -0
  165. package/kits/hub-game/code/client/soundscapeCourt.js +200 -0
  166. package/kits/hub-game/code/client/soundscapeCrowd.js +331 -0
  167. package/kits/hub-game/code/client/soundscapeCues.js +362 -0
  168. package/kits/hub-game/code/client/soundscapeMap.js +181 -0
  169. package/kits/hub-game/code/client/soundscapeMarket.js +176 -0
  170. package/kits/hub-game/code/client/soundscapeMusic.js +126 -0
  171. package/kits/hub-game/code/client/soundscapeMusicEngine.js +460 -0
  172. package/kits/hub-game/code/client/soundscapeSimlish.js +737 -0
  173. package/kits/hub-game/code/client/soundscapeSongs.js +127 -0
  174. package/kits/hub-game/code/client/soundscapeSongsRound3.js +63 -0
  175. package/kits/hub-game/code/client/soundscapeSynthesis.js +168 -0
  176. package/kits/hub-game/code/client/soundscapeUi.js +211 -0
  177. package/kits/hub-game/code/client/soundscapeVoice.js +1209 -0
  178. package/kits/hub-game/code/client/soundscapeWaves.js +206 -0
  179. package/kits/hub-game/code/client/spin.js +101 -0
  180. package/kits/hub-game/code/client/state.js +162 -1
  181. package/kits/hub-game/code/client/stuck.js +259 -0
  182. package/kits/hub-game/code/client/talk.js +714 -59
  183. package/kits/hub-game/code/client/tiers.js +543 -52
  184. package/kits/hub-game/code/client/toastBand.js +37 -0
  185. package/kits/hub-game/code/client/together.js +39 -2
  186. package/kits/hub-game/code/client/visibility.js +43 -0
  187. package/kits/hub-game/code/client/weakestLookBake.js +92 -0
  188. package/kits/hub-game/code/client/weakestTier.js +295 -0
  189. package/kits/hub-game/code/client/wear.js +461 -170
  190. package/kits/hub-game/code/client/worldLabels.js +241 -0
  191. package/kits/hub-game/code/client/yours.js +200 -0
  192. package/kits/hub-game/code/companionSpec.js +45 -0
  193. package/kits/hub-game/code/npcDisplayText.js +55 -0
  194. package/kits/hub-game/code/privateText.js +7 -0
  195. package/kits/hub-game/code/server/act.js +124 -0
  196. package/kits/hub-game/code/server/actions.js +138 -0
  197. package/kits/hub-game/code/server/actors.js +11 -2
  198. package/kits/hub-game/code/server/analytics.js +83 -0
  199. package/kits/hub-game/code/server/anonymousEntry.js +49 -0
  200. package/kits/hub-game/code/server/arrivalPose.js +36 -0
  201. package/kits/hub-game/code/server/ask.js +155 -0
  202. package/kits/hub-game/code/server/ballot.js +539 -0
  203. package/kits/hub-game/code/server/cells.js +100 -0
  204. package/kits/hub-game/code/server/companion.js +107 -0
  205. package/kits/hub-game/code/server/cues.js +70 -0
  206. package/kits/hub-game/code/server/decor.js +269 -0
  207. package/kits/hub-game/code/server/doorAnalytics.js +52 -0
  208. package/kits/hub-game/code/server/earned.js +478 -0
  209. package/kits/hub-game/code/server/frameBatch.js +183 -0
  210. package/kits/hub-game/code/server/friendBests.js +166 -0
  211. package/kits/hub-game/code/server/friendsAmong.js +272 -0
  212. package/kits/hub-game/code/server/history.js +7 -0
  213. package/kits/hub-game/code/server/hub.js +2510 -95
  214. package/kits/hub-game/code/server/idle.js +60 -12
  215. package/kits/hub-game/code/server/index.js +28 -6
  216. package/kits/hub-game/code/server/invites.js +19 -0
  217. package/kits/hub-game/code/server/labels.js +36 -2
  218. package/kits/hub-game/code/server/loadAbandon.js +106 -0
  219. package/kits/hub-game/code/server/manifest.js +586 -7
  220. package/kits/hub-game/code/server/menu.js +161 -0
  221. package/kits/hub-game/code/server/npcs.js +1025 -113
  222. package/kits/hub-game/code/server/observe.js +408 -0
  223. package/kits/hub-game/code/server/padOccupancy.js +85 -0
  224. package/kits/hub-game/code/server/party.js +2 -2
  225. package/kits/hub-game/code/server/players.js +30 -0
  226. package/kits/hub-game/code/server/resumePose.js +152 -0
  227. package/kits/hub-game/code/server/say.js +1 -1
  228. package/kits/hub-game/code/server/shot.js +110 -0
  229. package/kits/hub-game/code/server/standing.js +123 -0
  230. package/kits/hub-game/code/server/storageLimit.js +187 -0
  231. package/kits/hub-game/code/server/vis.js +175 -0
  232. package/kits/hub-game/code/server/wear.js +12 -0
  233. package/kits/hub-game/code/server/yours.js +59 -0
  234. package/kits/hub-game/code/shared/act.js +35 -0
  235. package/kits/hub-game/code/shared/cues.js +9 -0
  236. package/kits/hub-game/code/shared/danceIdle.js +28 -0
  237. package/kits/hub-game/code/shared/decor.js +41 -0
  238. package/kits/hub-game/code/shared/loadStages.js +12 -0
  239. package/kits/hub-game/code/shared/quality.js +74 -0
  240. package/kits/hub-game/code/shared/say.js +2 -0
  241. package/kits/hub-game/code/shared/shot.js +53 -0
  242. package/kits/hub-game/code/shared/spin.js +57 -0
  243. package/kits/hub-game/code/systems/hub.js +1753 -202
  244. package/kits/hub-game/docs/analytics.md +279 -0
  245. package/kits/hub-game/docs/content-pack.md +1 -1
  246. package/kits/hub-game/docs/contract.md +3475 -77
  247. package/kits/hub-game/docs/home-pieces.md +71 -0
  248. package/kits/hub-game/docs/observed-progress.md +252 -0
  249. package/kits/hub-game/main.jsx +2 -0
  250. package/kits/hub-game/models/avatar-10.pxmodel +28 -0
  251. package/kits/hub-game/models/avatar-11.pxmodel +28 -0
  252. package/kits/hub-game/models/avatar-12.pxmodel +27 -0
  253. package/kits/hub-game/models/avatar-13.pxmodel +24 -0
  254. package/kits/hub-game/models/avatar-14.pxmodel +29 -0
  255. package/kits/hub-game/models/avatar-15.pxmodel +24 -0
  256. package/kits/hub-game/models/avatar-4.pxmodel +29 -0
  257. package/kits/hub-game/models/avatar-5.pxmodel +27 -0
  258. package/kits/hub-game/models/avatar-6.pxmodel +26 -0
  259. package/kits/hub-game/models/avatar-7.pxmodel +25 -0
  260. package/kits/hub-game/models/avatar-8.pxmodel +24 -0
  261. package/kits/hub-game/models/avatar-9.pxmodel +30 -0
  262. package/kits/hub-game/models/earned/badge-round.pxmodel +100 -0
  263. package/kits/hub-game/models/earned/badge-shield.pxmodel +117 -0
  264. package/kits/hub-game/models/earned/badge-star.pxmodel +87 -0
  265. package/kits/hub-game/models/earned/belt-plain.pxmodel +72 -0
  266. package/kits/hub-game/models/earned/held-ball.pxmodel +43 -0
  267. package/kits/hub-game/models/earned/held-lantern.pxmodel +85 -0
  268. package/kits/hub-game/models/earned/held-net.pxmodel +57 -0
  269. package/kits/hub-game/models/earned/held-trophy.pxmodel +109 -0
  270. package/kits/hub-game/models/earned/pin-round.pxmodel +62 -0
  271. package/kits/hub-game/models/earned/sash-plain.pxmodel +66 -0
  272. package/kits/hub-game/models/earned/square/belt-plain.pxmodel +104 -0
  273. package/kits/hub-game/models/earned/square/sash-plain.pxmodel +98 -0
  274. package/kits/hub-game/models/hats/bat-clip.pxmodel +206 -0
  275. package/kits/hub-game/models/hats/beekeeper.pxmodel +149 -0
  276. package/kits/hub-game/models/hats/cap.pxmodel +162 -0
  277. package/kits/hub-game/models/hats/captain.pxmodel +178 -0
  278. package/kits/hub-game/models/hats/crooked-top.pxmodel +172 -0
  279. package/kits/hub-game/models/hats/flower-crown.pxmodel +451 -0
  280. package/kits/hub-game/models/hats/foam-crown.pxmodel +179 -0
  281. package/kits/hub-game/models/hats/lantern.pxmodel +230 -0
  282. package/kits/hub-game/models/hats/laurel.pxmodel +533 -0
  283. package/kits/hub-game/models/hats/lighthouse.pxmodel +96 -0
  284. package/kits/hub-game/models/hats/sailor.pxmodel +141 -0
  285. package/kits/hub-game/models/hats/souwester.pxmodel +131 -0
  286. package/kits/hub-game/models/hats/straw.pxmodel +139 -0
  287. package/kits/hub-game/models/hats/sunflower.pxmodel +406 -0
  288. package/kits/hub-game/models/hats/sweatband.pxmodel +112 -0
  289. package/kits/hub-game/models/hats/witch.pxmodel +147 -0
  290. package/kits/hub-game/package-lock.json +10 -1
  291. package/kits/hub-game/package.json +6 -2
  292. package/kits/hub-game/play/player.js +142 -0
  293. package/kits/hub-game/play/registry.js +47 -0
  294. package/kits/hub-game/play.jsx +37 -0
  295. package/kits/hub-game/scripts/check.mjs +117 -16
  296. package/kits/hub-game/scripts/companion-follower-wire.json +1 -0
  297. package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +132 -0
  298. package/kits/hub-game/scripts/fixtures/decor-keyless.json +293 -0
  299. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +26 -0
  300. package/kits/hub-game/scripts/fixtures/fake-dom.mjs +123 -0
  301. package/kits/hub-game/scripts/fixtures/interest-legacy.json +385 -0
  302. package/kits/hub-game/scripts/fixtures/npc-notes-v1.77.jsonl +4 -0
  303. package/kits/hub-game/scripts/fixtures/vis-shared-wire.json +1 -0
  304. package/kits/hub-game/scripts/gen-avatars.mjs +933 -16
  305. package/kits/hub-game/scripts/gen-earned.mjs +285 -0
  306. package/kits/hub-game/scripts/gen-hats.mjs +827 -0
  307. package/kits/hub-game/scripts/grab.before-orbit.mjs +400 -0
  308. package/kits/hub-game/scripts/pose-storage-fixture.mjs +46 -0
  309. package/kits/hub-game/scripts/soundscape-wave-analysis.mjs +125 -0
  310. package/kits/hub-game/scripts/test-act-client.mjs +186 -0
  311. package/kits/hub-game/scripts/test-act.mjs +171 -0
  312. package/kits/hub-game/scripts/test-action-layout.mjs +80 -0
  313. package/kits/hub-game/scripts/test-action-observers.mjs +46 -0
  314. package/kits/hub-game/scripts/test-actions-client.mjs +853 -0
  315. package/kits/hub-game/scripts/test-actions.mjs +298 -0
  316. package/kits/hub-game/scripts/test-actor-budget.mjs +44 -0
  317. package/kits/hub-game/scripts/test-actors.mjs +38 -23
  318. package/kits/hub-game/scripts/test-analytics.mjs +76 -0
  319. package/kits/hub-game/scripts/test-anonymous-entry.mjs +28 -0
  320. package/kits/hub-game/scripts/test-arrival-pose-server.mjs +196 -0
  321. package/kits/hub-game/scripts/test-arrival-pose.mjs +24 -0
  322. package/kits/hub-game/scripts/test-ask-client.mjs +358 -0
  323. package/kits/hub-game/scripts/test-ask-slot.mjs +85 -0
  324. package/kits/hub-game/scripts/test-ask.mjs +269 -0
  325. package/kits/hub-game/scripts/test-attention.mjs +10 -1
  326. package/kits/hub-game/scripts/test-avatar-cap.mjs +379 -0
  327. package/kits/hub-game/scripts/test-avatar-colors.mjs +72 -0
  328. package/kits/hub-game/scripts/test-avatar-models.mjs +181 -0
  329. package/kits/hub-game/scripts/test-avatar-share.mjs +318 -0
  330. package/kits/hub-game/scripts/test-avatar-wire.mjs +792 -0
  331. package/kits/hub-game/scripts/test-avatar.mjs +584 -7
  332. package/kits/hub-game/scripts/test-back-visibility.mjs +82 -0
  333. package/kits/hub-game/scripts/test-ballot.mjs +1008 -0
  334. package/kits/hub-game/scripts/test-ban-join.mjs +121 -13
  335. package/kits/hub-game/scripts/test-build.mjs +49 -0
  336. package/kits/hub-game/scripts/test-cells.mjs +71 -0
  337. package/kits/hub-game/scripts/test-chat.mjs +863 -0
  338. package/kits/hub-game/scripts/test-classic.mjs +2 -0
  339. package/kits/hub-game/scripts/test-companion-chat.mjs +216 -0
  340. package/kits/hub-game/scripts/test-companion-client.mjs +1167 -0
  341. package/kits/hub-game/scripts/test-companion.mjs +259 -0
  342. package/kits/hub-game/scripts/test-control-layout-dom.mjs +120 -0
  343. package/kits/hub-game/scripts/test-crowd-names.mjs +205 -0
  344. package/kits/hub-game/scripts/test-decor-client.mjs +344 -0
  345. package/kits/hub-game/scripts/test-decor.mjs +464 -0
  346. package/kits/hub-game/scripts/test-default-environment-root.mjs +95 -0
  347. package/kits/hub-game/scripts/test-default-environment.mjs +267 -0
  348. package/kits/hub-game/scripts/test-door-analytics.mjs +58 -0
  349. package/kits/hub-game/scripts/test-door-jump.mjs +100 -0
  350. package/kits/hub-game/scripts/test-earned-client.mjs +459 -0
  351. package/kits/hub-game/scripts/test-earned.mjs +1224 -0
  352. package/kits/hub-game/scripts/test-emote-bubble.mjs +110 -0
  353. package/kits/hub-game/scripts/test-far-avatars.mjs +340 -0
  354. package/kits/hub-game/scripts/test-fps-telemetry.mjs +112 -0
  355. package/kits/hub-game/scripts/test-frame-batch.mjs +252 -0
  356. package/kits/hub-game/scripts/test-fresh-friends.mjs +118 -0
  357. package/kits/hub-game/scripts/test-friend-bests.mjs +435 -0
  358. package/kits/hub-game/scripts/test-grab-orbit.mjs +961 -0
  359. package/kits/hub-game/scripts/test-grab.mjs +7 -0
  360. package/kits/hub-game/scripts/test-hats.mjs +422 -168
  361. package/kits/hub-game/scripts/test-high-only.mjs +170 -0
  362. package/kits/hub-game/scripts/test-hub-leaving.mjs +203 -0
  363. package/kits/hub-game/scripts/test-hub-ops.mjs +758 -2
  364. package/kits/hub-game/scripts/test-hub-trip.mjs +1594 -12
  365. package/kits/hub-game/scripts/test-hud-clear.mjs +484 -57
  366. package/kits/hub-game/scripts/test-hud-defects-dom.mjs +100 -0
  367. package/kits/hub-game/scripts/test-hud-rate.mjs +224 -0
  368. package/kits/hub-game/scripts/test-hud-safe-visibility-dom.mjs +83 -0
  369. package/kits/hub-game/scripts/test-idle.mjs +427 -1
  370. package/kits/hub-game/scripts/test-interest-cap.mjs +36 -0
  371. package/kits/hub-game/scripts/test-interest-cells.mjs +513 -0
  372. package/kits/hub-game/scripts/test-interest-client.mjs +118 -0
  373. package/kits/hub-game/scripts/test-interest.mjs +15 -0
  374. package/kits/hub-game/scripts/test-invites-client.mjs +430 -0
  375. package/kits/hub-game/scripts/test-invites.mjs +109 -0
  376. package/kits/hub-game/scripts/test-keys.mjs +46 -1
  377. package/kits/hub-game/scripts/test-labels.mjs +664 -0
  378. package/kits/hub-game/scripts/test-landscape-layout.mjs +194 -0
  379. package/kits/hub-game/scripts/test-list-scroll-dom.mjs +49 -0
  380. package/kits/hub-game/scripts/test-load-abandon.mjs +246 -0
  381. package/kits/hub-game/scripts/test-loading-cover.mjs +162 -0
  382. package/kits/hub-game/scripts/test-manifest.mjs +472 -0
  383. package/kits/hub-game/scripts/test-menu-client.mjs +585 -0
  384. package/kits/hub-game/scripts/test-menu.mjs +319 -0
  385. package/kits/hub-game/scripts/test-npcs.mjs +2528 -13
  386. package/kits/hub-game/scripts/test-object-entry.mjs +76 -0
  387. package/kits/hub-game/scripts/test-observed.mjs +745 -0
  388. package/kits/hub-game/scripts/test-pack.mjs +7 -0
  389. package/kits/hub-game/scripts/test-pad-cues.mjs +304 -0
  390. package/kits/hub-game/scripts/test-pad-occupancy.mjs +177 -0
  391. package/kits/hub-game/scripts/test-picker.mjs +541 -0
  392. package/kits/hub-game/scripts/test-placement-cache.mjs +690 -0
  393. package/kits/hub-game/scripts/test-progress-reset.mjs +559 -0
  394. package/kits/hub-game/scripts/test-push-visit.mjs +26 -0
  395. package/kits/hub-game/scripts/test-quality.mjs +385 -0
  396. package/kits/hub-game/scripts/test-rehello.mjs +1733 -0
  397. package/kits/hub-game/scripts/test-relations-among.mjs +222 -0
  398. package/kits/hub-game/scripts/test-relations-refresh.mjs +188 -0
  399. package/kits/hub-game/scripts/test-resume-action-order.mjs +598 -0
  400. package/kits/hub-game/scripts/test-resume-held.mjs +239 -0
  401. package/kits/hub-game/scripts/test-resume-pose.mjs +142 -0
  402. package/kits/hub-game/scripts/test-safe-events-dom.mjs +116 -0
  403. package/kits/hub-game/scripts/test-safe-layout.mjs +330 -0
  404. package/kits/hub-game/scripts/test-say.mjs +1 -1
  405. package/kits/hub-game/scripts/test-shot.mjs +901 -0
  406. package/kits/hub-game/scripts/test-signin-client.mjs +45 -0
  407. package/kits/hub-game/scripts/test-soundscape.mjs +5437 -0
  408. package/kits/hub-game/scripts/test-spin.mjs +314 -0
  409. package/kits/hub-game/scripts/test-standing.mjs +449 -0
  410. package/kits/hub-game/scripts/test-storage-limit.mjs +333 -0
  411. package/kits/hub-game/scripts/test-stuck.mjs +1904 -0
  412. package/kits/hub-game/scripts/test-talk-overlay-dom.mjs +130 -0
  413. package/kits/hub-game/scripts/test-tier-cells.mjs +706 -0
  414. package/kits/hub-game/scripts/test-tiers-render.mjs +412 -0
  415. package/kits/hub-game/scripts/test-tiers.mjs +476 -2
  416. package/kits/hub-game/scripts/test-toast-band.mjs +61 -0
  417. package/kits/hub-game/scripts/test-try-on.mjs +22 -22
  418. package/kits/hub-game/scripts/test-vis.mjs +770 -0
  419. package/kits/hub-game/scripts/test-visibility.mjs +134 -0
  420. package/kits/hub-game/scripts/test-weakest-tier.mjs +924 -0
  421. package/kits/hub-game/scripts/test-world-labels.mjs +367 -0
  422. package/kits/hub-game/scripts/test-yours-chrome.mjs +210 -0
  423. package/kits/hub-game/scripts/test-yours.mjs +403 -0
  424. package/kits/multiplayer-3d/CLAUDE.md +50 -0
  425. package/kits/multiplayer-3d/castle.json +5 -5
  426. package/kits/multiplayer-3d/code/client/avatars.js +7 -0
  427. package/kits/multiplayer-3d/code/client/gait.js +65 -0
  428. package/kits/multiplayer-3d/code/client/joinFailure.js +27 -0
  429. package/kits/multiplayer-3d/code/client/nameTags.js +59 -4
  430. package/kits/multiplayer-3d/code/client/resumeGate.js +139 -0
  431. package/kits/multiplayer-3d/code/options.js +5 -0
  432. package/kits/multiplayer-3d/code/server/ownership.js +10 -2
  433. package/kits/multiplayer-3d/code/server/sceneBodies.js +12 -0
  434. package/kits/multiplayer-3d/code/server/world.js +7 -0
  435. package/kits/multiplayer-3d/code/systems/multiplayer.js +443 -34
  436. package/kits/multiplayer-3d/package-lock.json +8 -1
  437. package/kits/multiplayer-3d/package.json +3 -1
  438. package/kits/multiplayer-3d/scripts/fixtures/README.md +11 -0
  439. package/kits/multiplayer-3d/scripts/fixtures/ownership-legacy.json +2 -0
  440. package/kits/multiplayer-3d/scripts/ownership-harness.mjs +102 -0
  441. package/kits/multiplayer-3d/scripts/ownership-loader.mjs +46 -0
  442. package/kits/multiplayer-3d/scripts/ownership-worker.mjs +15 -0
  443. package/kits/multiplayer-3d/scripts/record-ownership-session.mjs +98 -0
  444. package/kits/multiplayer-3d/scripts/test-eligible-claims.mjs +167 -0
  445. package/kits/multiplayer-3d/scripts/test-join-watchdog.mjs +436 -0
  446. package/kits/multiplayer-3d/scripts/test-own-name-tag.mjs +247 -0
  447. package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +624 -0
  448. package/kits/physics-2d/CLAUDE.md +19 -1
  449. package/kits/physics-2d/castle.json +2 -2
  450. package/kits/physics-2d/engine/frozenActors.js +233 -0
  451. package/kits/physics-2d/engine/scene.js +337 -3
  452. package/kits/physics-2d/engine/skyKey.js +129 -0
  453. package/kits/physics-2d/engine/stillClock.js +106 -0
  454. package/kits/physics-2d/engine/updateBudget.js +21 -0
  455. package/kits/physics-2d/eslint.config.js +1 -1
  456. package/kits/physics-2d/play/behaviors/AnalogStick.js +198 -0
  457. package/kits/physics-2d/play/behaviors/Camera.js +40 -0
  458. package/kits/physics-2d/play/behaviors/Collider.js +122 -0
  459. package/kits/physics-2d/play/behaviors/Draggable.js +115 -0
  460. package/kits/physics-2d/play/behaviors/Goal.js +46 -0
  461. package/kits/physics-2d/play/behaviors/Joints.js +126 -0
  462. package/kits/physics-2d/play/behaviors/Layout.js +71 -0
  463. package/kits/physics-2d/play/behaviors/RigidBody.js +57 -0
  464. package/kits/physics-2d/play/behaviors/Slingshot.js +142 -0
  465. package/kits/physics-2d/play/behaviors/SoundPlayer.js +263 -0
  466. package/kits/physics-2d/play/behaviors/Sprite.js +406 -0
  467. package/kits/physics-2d/play/behaviors/Style.js +209 -0
  468. package/kits/physics-2d/play/behaviors/Text.js +85 -0
  469. package/kits/physics-2d/play/behaviors/Video.js +93 -0
  470. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +326 -1
  471. package/kits/physics-3d/CLAUDE.md +42 -529
  472. package/kits/physics-3d/behaviors/Body.jsx +3 -0
  473. package/kits/physics-3d/behaviors/Model.jsx +3 -0
  474. package/kits/physics-3d/behaviors/Player.jsx +661 -87
  475. package/kits/physics-3d/behaviors/Shape.jsx +3 -0
  476. package/kits/physics-3d/behaviors/Solid.jsx +3 -0
  477. package/kits/physics-3d/behaviors/Transform.jsx +3 -0
  478. package/kits/physics-3d/castle.json +3 -3
  479. package/kits/physics-3d/docs/engine-camera.md +542 -0
  480. package/kits/physics-3d/docs/engine-frame-cap.md +136 -0
  481. package/kits/physics-3d/docs/engine-load.md +149 -0
  482. package/kits/physics-3d/docs/engine-look.md +114 -0
  483. package/kits/physics-3d/docs/engine-shadows.md +372 -0
  484. package/kits/physics-3d/docs/engine-skip-work.md +187 -0
  485. package/kits/physics-3d/docs/engine-sky.md +198 -0
  486. package/kits/physics-3d/docs/engine-static-actors.md +226 -0
  487. package/kits/physics-3d/docs/engine-view.md +37 -0
  488. package/kits/physics-3d/docs/pxmodel-format.md +9 -1
  489. package/kits/physics-3d/engine3d/PlayOnly3D.jsx +5 -1
  490. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +19 -277
  491. package/kits/physics-3d/engine3d/actornode.js +87 -0
  492. package/kits/physics-3d/engine3d/animationBudget.js +23 -0
  493. package/kits/physics-3d/engine3d/branches.js +3 -13
  494. package/kits/physics-3d/engine3d/cage.js +2 -7
  495. package/kits/physics-3d/engine3d/cageops.js +2 -17
  496. package/kits/physics-3d/engine3d/dataBehaviors.js +12 -0
  497. package/kits/physics-3d/engine3d/editorWorld.js +6 -0
  498. package/kits/physics-3d/engine3d/emptynodes.js +232 -0
  499. package/kits/physics-3d/engine3d/framecap.js +99 -0
  500. package/kits/physics-3d/engine3d/frozenphysics.js +140 -0
  501. package/kits/physics-3d/engine3d/frozenstatics.js +273 -0
  502. package/kits/physics-3d/engine3d/gait.js +126 -0
  503. package/kits/physics-3d/engine3d/initialModelFiles.js +18 -0
  504. package/kits/physics-3d/engine3d/kithooks.js +47 -0
  505. package/kits/physics-3d/engine3d/look.js +514 -48
  506. package/kits/physics-3d/engine3d/lookbake.js +208 -0
  507. package/kits/physics-3d/engine3d/materialpresets.js +2 -0
  508. package/kits/physics-3d/engine3d/modelFiles.js +3 -17
  509. package/kits/physics-3d/engine3d/modelMath.js +49 -0
  510. package/kits/physics-3d/engine3d/modelready.js +16 -0
  511. package/kits/physics-3d/engine3d/motion.js +39 -10
  512. package/kits/physics-3d/engine3d/nearshadows.js +106 -21
  513. package/kits/physics-3d/engine3d/optimize.js +9 -5
  514. package/kits/physics-3d/engine3d/orbitinput.js +522 -10
  515. package/kits/physics-3d/engine3d/orbitlens.js +48 -0
  516. package/kits/physics-3d/engine3d/ownmodel.js +213 -0
  517. package/kits/physics-3d/engine3d/partgeometry.js +1 -16
  518. package/kits/physics-3d/engine3d/paths.js +1 -9
  519. package/kits/physics-3d/engine3d/playTimings.js +50 -0
  520. package/kits/physics-3d/engine3d/playerRun.js +372 -0
  521. package/kits/physics-3d/engine3d/pxmodel.js +42 -11
  522. package/kits/physics-3d/engine3d/rapier.js +27 -0
  523. package/kits/physics-3d/engine3d/scatter.js +1 -11
  524. package/kits/physics-3d/engine3d/shadowfade.js +890 -0
  525. package/kits/physics-3d/engine3d/sky.js +547 -0
  526. package/kits/physics-3d/engine3d/skylife.js +306 -0
  527. package/kits/physics-3d/engine3d/squarefirst.js +177 -0
  528. package/kits/physics-3d/engine3d/stillshadows.js +399 -0
  529. package/kits/physics-3d/engine3d/sweep.js +1 -25
  530. package/kits/physics-3d/engine3d/unchanged.js +11 -0
  531. package/kits/physics-3d/engine3d/viewrange.js +52 -0
  532. package/kits/physics-3d/engine3d/world3d.js +1253 -76
  533. package/kits/physics-3d/eslint.config.js +2 -1
  534. package/kits/physics-3d/main.jsx +10 -2
  535. package/kits/physics-3d/package-lock.json +7 -0
  536. package/kits/physics-3d/package.json +5 -1
  537. package/kits/physics-3d/play/behaviors/Body.js +31 -0
  538. package/kits/physics-3d/play/behaviors/Door.js +37 -0
  539. package/kits/physics-3d/play/behaviors/Lookable.js +16 -0
  540. package/kits/physics-3d/play/behaviors/Model.js +23 -0
  541. package/kits/physics-3d/play/behaviors/Pickup.js +46 -0
  542. package/kits/physics-3d/play/behaviors/Player.js +1204 -0
  543. package/kits/physics-3d/play/behaviors/Shape.js +47 -0
  544. package/kits/physics-3d/play/behaviors/Solid.js +16 -0
  545. package/kits/physics-3d/play/behaviors/Transform.js +29 -0
  546. package/kits/physics-3d/pnpm-lock.yaml +8 -0
  547. package/kits/physics-3d/scripts/bench-shadow-fade.mjs +37 -0
  548. package/kits/physics-3d/scripts/build-rapier-gz.mjs +56 -0
  549. package/kits/physics-3d/scripts/frozen-statics-fixture.mjs +141 -0
  550. package/kits/physics-3d/scripts/look-baseline.mjs +155 -0
  551. package/kits/physics-3d/scripts/test-camera-follow.mjs +5 -1
  552. package/kits/physics-3d/scripts/test-camera-orbit.mjs +2613 -82
  553. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +2 -2
  554. package/kits/physics-3d/scripts/test-empty-gait-hints.mjs +89 -0
  555. package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +438 -0
  556. package/kits/physics-3d/scripts/test-frame-cap.mjs +452 -0
  557. package/kits/physics-3d/scripts/test-frozen-nested.mjs +49 -0
  558. package/kits/physics-3d/scripts/test-frozen-statics-legacy-physics2d.mjs +123 -0
  559. package/kits/physics-3d/scripts/test-frozen-statics.mjs +434 -0
  560. package/kits/physics-3d/scripts/test-gait.mjs +387 -0
  561. package/kits/physics-3d/scripts/test-look-bake.mjs +1056 -0
  562. package/kits/physics-3d/scripts/test-model-parse-cache.mjs +92 -0
  563. package/kits/physics-3d/scripts/test-near-shadows.mjs +5 -2
  564. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +2001 -0
  565. package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +582 -0
  566. package/kits/physics-3d/scripts/test-orbit-shot.mjs +657 -0
  567. package/kits/physics-3d/scripts/test-orbit-view.mjs +230 -0
  568. package/kits/physics-3d/scripts/test-rapier-gz.mjs +106 -0
  569. package/kits/physics-3d/scripts/test-skip-empty-nodes.mjs +845 -0
  570. package/kits/physics-3d/scripts/test-sky.mjs +2470 -0
  571. package/kits/physics-3d/scripts/test-square-first.mjs +921 -0
  572. package/kits/physics-3d/scripts/test-static-actors.mjs +10 -1
  573. package/kits/physics-3d/scripts/test-static-physics.mjs +4 -1
  574. package/kits/physics-3d/scripts/test-static-scenery.mjs +2174 -0
  575. package/kits/physics-3d/scripts/test-steady-hover.mjs +7 -2
  576. package/kits/physics-3d/scripts/test-still-shadows.mjs +477 -0
  577. package/kits/physics-3d/scripts/test-view-range.mjs +260 -0
  578. package/kits/physics-3d/systems/physics3d.js +419 -9
  579. package/kits/real-time/castle.json +2 -2
  580. package/kits/real-time/code/client/connection.js +33 -10
  581. package/kits/real-time/code/client/gameHooks.js +2 -0
  582. package/kits/real-time/code/client/joinOverlay.js +9 -4
  583. package/kits/real-time/code/server/gameHooks.js +7 -0
  584. package/kits/real-time/code/server/session.js +102 -22
  585. package/kits/real-time/package-lock.json +1 -1
  586. package/package.json +2 -2
  587. package/dist/shell/assets/index-Cf61cNfT.css +0 -1
@@ -26,12 +26,15 @@ import { setup, initCard, Store, Leaderboard } from "castle-web-sdk";
26
26
  - [Pass](#pass)
27
27
  - [Snapshot](#snapshot)
28
28
  - [Portal](#portal)
29
+ - [Social](#social)
30
+ - [Party](#party)
29
31
  - [Hub](#hub)
30
32
  - [Decks](#decks)
31
33
  - [Clipboard](#clipboard)
32
34
  - [Haptics](#haptics)
33
35
  - [Agent](#agent)
34
36
  - [Lifecycle](#lifecycle)
37
+ - [Display](#display)
35
38
  - [Multiplayer](#multiplayer)
36
39
  - [Setup](#setup)
37
40
  - [Saving files](#writefilepath-contents-promisevoid)
@@ -64,7 +67,25 @@ Named rooms use `{ mode: "named", key: "room-name" }`; party sessions use
64
67
  reconnects temporary socket drops automatically. `onStateChange` reports
65
68
  `acquiring`, `connecting`, `connected`, `reconnecting`, and `closed`; its optional
66
69
  metadata distinguishes a server `bye`, a replaced server version, an explicit
67
- `leave`, and connection failures.
70
+ `leave`, and connection failures. The reconnect retry budget counts 30 seconds
71
+ of foreground time; time while the page is hidden or frozen does not spend it,
72
+ and a stall of the page's JavaScript (a debugger pause, an app pausing its web
73
+ view) spends at most two seconds. After any return the SDK tries the reconnect
74
+ credential at least once before giving up on it. Retries wait for the page to
75
+ become visible and resume. A server rejecting the
76
+ credential or confirming the session ended can still trigger a fresh join sooner.
77
+
78
+ `connection.serverBundleId` and `connection.serverBundleSha256` identify the server publication running the connected session. These read-only diagnostics are `null` before a live connection, while disconnected, in solo mode, or when the host does not provide them. The ID identifies a publication; the SHA-256 identifies its code bytes, so two publications can share a hash. Read the values again after a reconnect or a destination join. They describe the running server, not the client bundle or the deck’s newest save.
79
+
80
+ Experimental: `Multiplayer.join({ mode: "public", pongTimeoutMs: 10_000 })`
81
+ reconnects if a keepalive ping receives no pong within the given milliseconds.
82
+ Omitting the option (or passing `0`) preserves the existing keepalive behavior.
83
+ The deadline starts at a ping, normally sent every 25 seconds; it is not a
84
+ deadline for game messages. A deadline callback delayed by more than one second (for example during page
85
+ suspension) sends one fresh ping and waits a full deadline before reconnecting. Only one
86
+ such extension is allowed without a pong, so repeated timer throttling cannot
87
+ postpone recovery indefinitely.
88
+
68
89
  During local development, reloading a Play panel restores that panel's session
69
90
  when its dev server is still running. A separate Play panel joins separately.
70
91
 
@@ -147,10 +168,34 @@ export default {
147
168
 
148
169
  `session.storage.deck` is shared by everyone playing.
149
170
  `session.storage.user(userId)` is one player's public data.
171
+ `await session.storage.playthrough(userId)` opens that player's generation-bound
172
+ game state. Its `resetGeneration` is present only after an administrator has
173
+ reset that player's progress for this deck. It is a monotonic reset marker,
174
+ separate from the handle's `generation`, which fences playthrough operations.
175
+ Deck-scope storage writes are not fenced by either generation; a server using
176
+ `session.storage.deck` must discard its own stale queued writes and cached
177
+ per-player values when it observes a newer reset marker.
150
178
  `session.storage.board(name)` is a leaderboard. The root and its buckets also
151
179
  support the [atomic save API](#atomic-saves). Each scope has the same
152
180
  `get`, `set`, `remove`, `increment` and `list` as `Store`.
153
181
 
182
+ `session.storage.town(userId)` lets a door deck's server read and write one
183
+ signed-in player's rows in its source town's deck scope, for things such as
184
+ hats bought in town. It has `get`, `set`, `remove` and `increment`; quota counts
185
+ against the town. Every key is one of the town's per-player namespaces
186
+ (`tokens`, `spent`, `own`, `hat`, `chirp`) followed by the user id: for user
187
+ `7`, `own:7:tophat` and `hat:7` work; `own:tophat:7` and `quay:7` do not. The
188
+ rest of the town's rows are its own. The player must be live in this session
189
+ (a player who joined a few seconds ago can briefly get
190
+ `CAULDRON_HUB_NOT_IN_SESSION`, so retry later rather than giving up); in a house, only the owner's rows are
191
+ accessible. Calls reject with `CAULDRON_HUB_NO_TOWN` without a source town
192
+ (including a town calling it), `CAULDRON_HUB_NOT_IN_SESSION` for an absent
193
+ player, or `CAULDRON_HUB_NOT_OWNER` for someone other than the house's owner.
194
+ Invalid key segments reject with `CAULDRON_STORAGE_INVALID_ARGUMENT`.
195
+ During dev serve, keys live under `town/` in the dev deck's own deck scope,
196
+ so testing a door never changes a real town. An unpublished deck still needs
197
+ a published deck id for storage.
198
+
154
199
  Two differences follow from a session server not being a player:
155
200
 
156
201
  - **It owns `deck` scope.** Once a deck has a published server, clients read
@@ -173,12 +218,28 @@ kit's contract). `save-deck` publishes the block's titles and result shapes with
173
218
  the server bundle, and Castle pins them to every session of the place. Those
174
219
  sessions have `session.hub`; every other session has `session.hub === null`.
175
220
 
221
+ `session.hub.owner` is the owner's user id string on an owner door instance,
222
+ passed by the platform. It is absent on every other hub session, including the
223
+ dev serve.
224
+
176
225
  - `session.hub.place`, `.title` and `.result` are the place and the result shape
177
226
  as published (`result` is `null` for a place that reports none, such as a town).
227
+ - `session.hub.reconnectWindowMs`, when present, is Castle's pinned hub-place
228
+ reconnect grace in milliseconds, inclusive at the deadline. It is absent on
229
+ sessions without a pinned grace and older hosts. Kits use it to match visit retention to the
230
+ transport window; deck code does not choose it.
178
231
  - `session.hub.arrival(playerId)` is how a player came in when Castle placed them
179
232
  through a hub door: `{ fromDeckId, doorId }` (`doorId` is `null` when the door
180
233
  names none), else `null`. It is Castle's word, never a client's, and it is also
181
234
  the third argument of `onPlayerJoin`.
235
+ - `session.hub.push` is optional, present only for a place declaring
236
+ `hub.push: { version: 1 }` on a capable runtime. Its
237
+ `visit(playerId, { userId, timezone })` reports a visit with the captured
238
+ authenticated account and an IANA timezone. It returns a boolean acknowledgement.
239
+ Ghost derives the three-day come-back reminder and checks consent, answered
240
+ age, experiments, quiet hours and delivery limits. Reporting a visit does not
241
+ opt the player in or promise a notification. No crop reporting or queue
242
+ reconciliation API is exposed.
182
243
  - `session.hub.reportResult(playerId, { outcome?, score?, stats? })` records a
183
244
  signed-in player's result for this visit, once. The host checks it against the
184
245
  published shape and Castle keeps it only for a place behind a curated door;
@@ -199,6 +260,46 @@ sessions have `session.hub`; every other session has `session.hub === null`.
199
260
  id the kit draws, `color` `'#rrggbb'`, `rarity` 0-9), or clears it with `null`;
200
261
  the latest wins. Castle takes it only from a curated hub place. Resolves
201
262
  `{ wearable }`; `readResults` returns it as `players[userId].wearable`.
263
+ - `session.hub.unlock(playerId, itemId)` gives a signed-in player one of the
264
+ deck's declared earned items (castle.json `hub.unlocks`: `{ id, class, shape,
265
+ name, deed, color }`, at most 8, `class` one of `badge`, `pin`, `belt`, `sash`,
266
+ `held`). v1.70 also permits up to 6 home items separately: `furniture` or
267
+ `deed`, with `piece` in place of `shape` (the same lowercase id format).
268
+ Each id is unique across both lists. Castle takes it only from a curated hub
269
+ place and only for an id the saved deck declares; a first wearable unlock
270
+ is also shown. Resolves
271
+ `{ unlocked: true, isNew, earned }`, where `earned` is what the player now
272
+ shows (`{ deckId, id, class, shape, name, deed, color }`) or `null`, including
273
+ for home grants. A home grant never changes what the avatar shows; a home
274
+ item appears only in the owned list returned by `readUnlocks`.
275
+ `readResults` returns the shown one as `players[userId].earned`, absent when
276
+ none.
277
+ - `session.hub.wearEarned(playerId, { deckId, id } | null)` chooses which owned
278
+ earned item a player shows, or none. Castle takes it only from the town.
279
+ Home items are refused with `CAULDRON_HUB_EARNED_NOT_WEARABLE`.
280
+ Resolves `{ earned }`.
281
+ - `session.hub.readUnlocks(userIds)` reads the earned items players here own:
282
+ `{ players: { [userId]: { owned: [...] } } }`, including home items with
283
+ their `class` and `piece`. `MultiplayerHubEarnedItem` and
284
+ `MultiplayerHubEarnedClass` describe wearable items only;
285
+ `MultiplayerHubHomeItem` and `MultiplayerHubHomeClass` describe home items.
286
+ Only the owned list uses the union of both item types; unlock/wear receipts
287
+ and arrival results keep the wearable-only type.
288
+ - These three reject with `CAULDRON_HUB_UNAVAILABLE` on a runtime without them.
289
+ - `session.hub.friendsAmong(playerId, userIds)` resolves the subset of candidate
290
+ user ids that are this connected player's friends (`Promise<string[]>`).
291
+ The platform checks mutual follows, age, blocks, the hub gate and the player's
292
+ recent client friends ask. It uses `hubFriendsAmong` or the older runtime's
293
+ storage broker and rejects on platform errors. The hub-game kit wraps it with
294
+ decimal-id filtering, a 100-candidate cap, caching and a silent `[]` fallback.
295
+ - `session.hub.relationsAmong(playerId, userIds)` makes the same single host read
296
+ and resolves `{ friends, follows, followedBy }`, each limited to asked string
297
+ ids. Missing lists are empty on older hosts. Mutual friends keep the chat age
298
+ and block rules; follows in either direction require no block, with no age rule.
299
+ These lists belong to the viewer only and must never go to another client.
300
+ Optional third argument `{ strict: true }` rejects malformed raw lists before
301
+ normalization and adds `validated: true` to a successful result. Without it,
302
+ the existing response shape and older-host behavior remain unchanged.
202
303
  - `session.hub.hiddenPair(playerIdA, playerIdB)` is true when a block hides these
203
304
  two players from each other (either one blocked the other). Never send either
204
305
  one the other's pose, avatar or name. The block lists themselves never reach
@@ -567,6 +668,72 @@ claim can fail with writer loss while `committed === true` and its original
567
668
  receipt; it never takes ownership again. Transport ambiguity keeps the outcome
568
669
  unknown until receipt lookup or identical replay settles it.
569
670
 
671
+ ### Conditional writes and recovery (gated)
672
+
673
+ `Store.conditionalWrite(input)` and `session.storage.conditionalWrite(input)`
674
+ use the same request and receipt as `transaction`. Read with `snapshot`, then
675
+ pass its `access` and each target's `revision` as `expectedAccess` and
676
+ `expectedRevision`. Use `null` to create an absent target. A revision belongs
677
+ to a **prefix**, so changing any key in it changes the revision. For an
678
+ independent value, give it a separate, non-overlapping prefix.
679
+
680
+ This additive API is off by default. The platform must enable conditional
681
+ storage for the deck after its database index and host support are ready.
682
+ Older hosts and the dev memory store do not support it. Keep a dependent
683
+ feature off when the API is unavailable; never fall back to ordinary writes.
684
+ Existing `get`, `set` and save methods keep their behavior.
685
+
686
+ Session servers can read `session.storage.resetGeneration(userId)` (zero before
687
+ the first reset) and pass `resetFences: [{ playerId, resetGeneration }]` to
688
+ `conditionalWrite`. Supply one or two unique numeric account IDs and integer
689
+ generations from 0 through 2147483647. Read generations before the snapshot used
690
+ to build the write. A reset that commits first refuses the write with
691
+ `CAULDRON_STORAGE_STALE_RESET_GENERATION`, `committed: false`, and
692
+ `playerId`, `expectedResetGeneration`, and current `resetGeneration` on the
693
+ `SaveError` and its `extensions`. A write that commits first retains its receipt;
694
+ recovery must check current generations before adopting it. Clients cannot send
695
+ reset fences. Omitting them preserves the existing request.
696
+
697
+ One call changes up to eight targets, with up to eight explicit key changes
698
+ per target, across the same deck and at most two players. Every target needs
699
+ its expected revision. A read-only `check` can use `expectedRevision: null`
700
+ to require absence without creating that target. All changes commit together. Clients may address their
701
+ own user/private targets and writable deck targets; only the deck server can
702
+ condition on another player's user target. Servers cannot access private data.
703
+ Existing quota, byte and rate allowances still apply. A prefix replacement
704
+ also removes its previous rows, subject to those allowances.
705
+
706
+ On a revision conflict, `SaveError.code` is
707
+ `CAULDRON_STORAGE_REVISION_CONFLICT`, `committed` is `false`, and `current`
708
+ contains the current values and revisions read at the failed comparison.
709
+ If that full snapshot exceeds the byte allowance, the call fails with
710
+ `CAULDRON_STORAGE_TOO_LARGE`; no changes commit. Keep the player's proposed
711
+ change and reload before offering another choice.
712
+
713
+ Use a unique `operationId` for each action. Retrying the **identical request**
714
+ after a lost reply returns its original committed receipt, even if values
715
+ have since changed. Reusing the ID with different input is refused. Failed
716
+ comparisons do not create receipts. Receipts have no automatic expiry and
717
+ are retained beyond 24 hours; an explicit data/account reset may remove them.
718
+ Never reuse old operation IDs or access tokens after a reset.
719
+
720
+ `recentOperations({ limit?, cursor? })`, on both root APIs, discovers the
721
+ caller's committed operation IDs after a restart. It returns
722
+ `{ operations: [{ operationId, committedAt, receipt }], cursor }`, newest
723
+ first. `limit` defaults to 16 and is at most 32; pass the returned cursor for
724
+ the next page. This lists existing save receipts too. Client and server
725
+ histories are separate; all layers of the same deck share the server history.
726
+ Use a smaller limit if the reply exceeds the byte allowance. A history page
727
+ is discovery, not a snapshot of current values: reload with `snapshot` before
728
+ building the next change. `operation(id)` still looks up a known ID.
729
+
730
+ Pairing can atomically create a project and reserve both players' recovery
731
+ entries. The game server must still validate consent, membership and editing
732
+ leases. A market sale can atomically update stock, the daily cap and the
733
+ purse, once **every** writer of those values uses the managed targets.
734
+ Durable game recovery entries belong in those targets; recent operation
735
+ receipts alone do not define permanent project ownership or sale policy.
736
+
570
737
  ### Save coordinator
571
738
 
572
739
  `createSaveCoordinator`, from `castle-web-sdk` or `castle-web-sdk/server`,
@@ -895,7 +1062,7 @@ itself (ones Castle runs across decks), on the serve only.
895
1062
 
896
1063
  The player's platform avatar: one per account, worn in every hub place
897
1064
  (cauldron-game-server `docs/HUB.md`, decision 4). In v1 it is an index into the
898
- hub-game kit's character templates; there is no editor and no cosmetics. The
1065
+ hub-game kit's character templates, with an optional colour choice. The
899
1066
  hub-game kit is the caller: it dresses the player and offers the choice in its
900
1067
  picker. Other players' avatars are not read here; a place's server learns them
901
1068
  from ghost.
@@ -907,7 +1074,7 @@ every account has (`chosen: false`). Anonymous accounts have one too.
907
1074
  `{ status: "unavailable", avatar: null }` for a signed-out visitor; a host from
908
1075
  before avatars rejects with `UNKNOWN_COMMAND`. Either way the deck picks its own.
909
1076
 
910
- ### `Avatar.set(avatar): Promise<AvatarResult>`
1077
+ ### `Avatar.set(avatar, options?: { color?: number }): Promise<AvatarResult>`
911
1078
 
912
1079
  Makes `avatar` the account's from now on, everywhere. Only a curated hub place
913
1080
  (a deck an enabled hub door leads into or out of) may: anywhere else, and for a
@@ -915,6 +1082,15 @@ signed-out visitor, the answer is `unavailable` and nothing changes. Ghost
915
1082
  refuses an index outside its template set (`INVALID_ARGUMENT`) and more than 30
916
1083
  choices a minute (`RATE_LIMIT_EXCEEDED`).
917
1084
 
1085
+ A host that supports avatar colours includes `color` in `AvatarResult`; the
1086
+ field is absent from older hosts. `Avatar.colors === true` marks an SDK whose
1087
+ `Avatar.set` carries `{ color }`; the hub-game kit requires both the host field
1088
+ and this marker to offer platform colours. Only after that support is known, pass
1089
+ `{ color }` to choose a non-negative integer colour for the current avatar.
1090
+ The host accepts 0–255; ghost holds the offered range. Changing character
1091
+ without options clears its colour. Omitting colour sends the existing command
1092
+ and mutation unchanged. The read query will ask for colour once ghost serves it.
1093
+
918
1094
  ## Pass
919
1095
 
920
1096
  A pass is something a creator sells to players for Castle bricks (the
@@ -1008,14 +1184,128 @@ Snapshot.onTaken(() => {
1008
1184
  });
1009
1185
  ```
1010
1186
 
1187
+ ## Social
1188
+
1189
+ `Social` gives a Cauldron deck the signed-in player's mutual Castle follows.
1190
+ The host supplies the player and current deck from trusted play context; a deck
1191
+ cannot ask about another account or deck. A host from before Social rejects with
1192
+ `CastleError` code `UNKNOWN_COMMAND`.
1193
+
1194
+ - `Social.friends()` returns at most 20 mutual follows as
1195
+ `{ userId, username, photoUrl? }`. A one-way follow is not a friend here.
1196
+ - `Social.presence()` returns the mutual friends playing this deck now as
1197
+ `{ userId, username, photoUrl?, sessionId, routeId?, slot?, updatedAt }`.
1198
+ Castle's now-playing privacy and multiplayer gates apply. It fails closed to
1199
+ `[]` when presence is gated or unavailable.
1200
+
1201
+ Presence has no event in v1. Poll `Social.presence()` when the game needs to
1202
+ refresh its list; do not treat `updatedAt` as a durable offline record.
1203
+
1204
+ ```js
1205
+ import { Social } from "castle-web-sdk";
1206
+
1207
+ const friends = await Social.friends();
1208
+ const playingHere = await Social.presence();
1209
+ ```
1210
+
1211
+ ## Party
1212
+
1213
+ `Party` creates and drives Castle parties with the signed-in player's account.
1214
+ Castle still enforces membership, roles, age and party permissions; refusals are
1215
+ `CastleError`s carrying the server's code. Party and user-id arrays are bounded
1216
+ to 32 users.
1217
+
1218
+ - `Party.current()` returns the party this play was launched with as
1219
+ `{ partyId, name, status, hasUnreadMessages }`, or `null`. The party id comes
1220
+ only from trusted host context, and no request is made when the play has none.
1221
+ - `Party.create(userIds)` creates a party containing those users and the
1222
+ signed-in player. It never sets an initial deck. Creating one does not change
1223
+ `Party.current()` or the launch party used by
1224
+ `Multiplayer.join({ mode: "party" })`.
1225
+ - `Party.invite(partyId, userIds)` invites more users.
1226
+ - `Party.respond(partyId, accept)` accepts or rejects an invitation.
1227
+ - `Party.members(partyId)` returns
1228
+ `{ userId, username, photoUrl?, status, role }` rows. `role` is `member`,
1229
+ `host` or `owner`.
1230
+ - `Party.leave(partyId)` leaves the party.
1231
+ - `Party.messages(partyId, cursor?)` returns
1232
+ `{ messages, cursor }`. Messages are newest first; pass the cursor to load
1233
+ **older** history (the opposite direction from `Hub.chat(after)`). Each message
1234
+ has `{ id, fromUserId, fromUsername, body, text, createdAt }`. `body` is the
1235
+ Castle chat JSON; `text` is non-null only when that body is plain text with no
1236
+ tags, links or embeds.
1237
+ - `Party.say(partyId, text)` sends plain text to the party. The host trims it
1238
+ and caps it at 1,000 characters, then returns the stored `PartyMessage`.
1239
+
1240
+ ```js
1241
+ import { Party } from "castle-web-sdk";
1242
+
1243
+ const party = await Party.current();
1244
+ if (party) {
1245
+ const page = await Party.messages(party.partyId);
1246
+ await Party.say(party.partyId, "Meet by the gate!");
1247
+ }
1248
+ ```
1249
+
1011
1250
  ## Hub
1012
1251
 
1252
+ Hub contract v1.95 adds optional invites. A place declaring `hub.invite: true`
1253
+ can call `hub.invite(playerId)` on its server to offer **Invite a friend**.
1254
+ As of contract v1.124, `Hub.invite()` makes one link for up to five friends,
1255
+ expiring within 24 hours. The kit opens it directly with native Share when
1256
+ supported and an explicit Copy link action. `Hub.invite({ crew: false })`
1257
+ retains the one-use option for callers that need it. Hosts without invite
1258
+ support return `unavailable`.
1259
+
1260
+ `Hub.canInvite()` answers `{ status: 'ok', canInvite }`: whether the host will
1261
+ make a link for this player, by Castle's invite rule for the account (signed
1262
+ in, over 13, in the invite audience). The kit offers **Invite a friend** only on
1263
+ `canInvite: true`. Hosts without hub support answer `unavailable`, and a host
1264
+ older than the command rejects it, so treat anything else as no.
1265
+ With `canInvite: true`, newer hosts also name the account the links belong to
1266
+ (`userId`, a guest's included); the kit offers the action only while that
1267
+ account is the player's own, and checks `User.getCurrent()` when a host names
1268
+ none.
1269
+
1270
+ The trusted host resolves the link after sign-in, retains its token, and requests
1271
+ the inviter's layer when it has room. If resolution refuses the invite, the host
1272
+ discards it for that visit and joins normally. Transient resolution failures
1273
+ retry with backoff; after five failures the host also discards the invite.
1274
+ Anonymous players join normally without using the invite.
1275
+ An invite can also route through the
1276
+ existing `Hub.inviteArrival()` result `{ status: 'route', doorId }` to the
1277
+ inviter's house or active run behind a curated door that allows late joins.
1278
+ Contract v1.113 active-run routing requires root `hub.bringFriend: true`
1279
+ in addition to `invite: true` on both the town and destination. The destination
1280
+ also declares `hub.bringFriend: true` so its saved bundle and fresh pin retain
1281
+ the invite capability;
1282
+ it admits only to the matching live run while the inviter is present. A full,
1283
+ ended or unavailable run is refused rather than recreated. The kit calls
1284
+ `Hub.inviteArrival()` after joining that destination. Ghost verifies arrival
1285
+ before creating mutual follows between each eligible
1286
+ over-13 arrival and the inviter. New arrivals do not follow one another;
1287
+ existing pairs from earlier links remain available for Undo. Under-13 arrivals create no follows. The arrival
1288
+ surface shows an authored now-friends line and `Hub.undoInvite(userId)` removes
1289
+ both follow directions for that pair. No player-entered message travels with a link.
1290
+ These operations retain the existing hub access gates. Link creation and arrival
1291
+ completion wait up to 16 seconds when the server presence roster is still catching
1292
+ up with the game connection.
1293
+
1013
1294
  `Hub` moves a player between hub places: every deck built on the hub-game kit is
1014
1295
  a place, and a door is a row in Castle's curated door table. A deck names only a
1015
1296
  door; the host supplies the current place, the session it joined there and the
1016
1297
  party, and calls Castle with the player's own account. Hosts without hub support
1017
1298
  answer `unavailable`; older hosts reject with `CastleError` code `UNKNOWN_COMMAND`.
1018
1299
 
1300
+ `Hub.signIn({ reason })` asks the host to open its native sign-in flow for an
1301
+ anonymous player. `reason` is the short explanation shown to the player (at most
1302
+ 200 characters and 512 UTF-8 bytes). It resolves to
1303
+ `{ status: 'signedIn', userId? }`, `{ status: 'dismissed' }`, or
1304
+ `{ status: 'unavailable' }`. `userId` is present only when the host can return
1305
+ the signed-in account id. A new host without native sign-in support returns
1306
+ `unavailable`; an older host that does not know this command rejects with
1307
+ `UNKNOWN_COMMAND`.
1308
+
1019
1309
  - `Hub.doors()` reads the current place's doors and who is inside them:
1020
1310
  `{ status: "ok", doors }` or `{ status: "unavailable", doors: null }`. A row has
1021
1311
  `doorId`, `launcherKind` (`door`, `table`, `cabinet`, `gate`), `placementKind`
@@ -1024,6 +1314,10 @@ answer `unavailable`; older hosts reject with `CastleError` code `UNKNOWN_COMMAN
1024
1314
  - `Hub.go(doorId)` acquires the destination behind a door of the current place.
1025
1315
  A door used within seconds of arriving can take up to 15 seconds to answer
1026
1316
  while Castle catches up with the arrival.
1317
+ `Hub.go(doorId, { ownerUserId })` on a House door visits that friend's House
1318
+ (the `ownerUserId` `Hub.friends()` gives a friend at home); Castle admits it
1319
+ only while the two are connected and the owner is home. A host that predates
1320
+ it ignores `ownerUserId` and acquires the player's own House.
1027
1321
  - `Hub.back()` acquires the way back through the door the player came in by: the
1028
1322
  layer they left if it has room, else their party's, else the usual pick. The
1029
1323
  deck cannot choose where it leads; `not_found` when there is no way back.
@@ -1032,7 +1326,9 @@ answer `unavailable`; older hosts reject with `CastleError` code `UNKNOWN_COMMAN
1032
1326
  20): `{ status: "ok", friends: [{ userId, username, here, door }] }` or
1033
1327
  `{ status: "unavailable", friends: null }`. `here` is true for a friend in the
1034
1328
  player's own layer; `door` is set instead for a friend inside the place behind
1035
- one of this place's doors (that door's id), and null otherwise.
1329
+ one of this place's doors (that door's id), and null otherwise. A friend
1330
+ inside their own House behind that door also has `home: true` and
1331
+ `ownerUserId`, which `Hub.go` takes to visit them.
1036
1332
  - `Hub.jump(userId)` acquires the layer of the current place that friend is in:
1037
1333
  the same place in another session, joined exactly like a door's. The way back
1038
1334
  does not change. `not_found` when the friend is not in another layer of it.
@@ -1053,7 +1349,13 @@ answer `unavailable`; older hosts reject with `CastleError` code `UNKNOWN_COMMAN
1053
1349
  send it to), `refused`, `limited` (said too fast) or `unavailable`.
1054
1350
  - `Hub.reportChat(messageId)` reports a chat message the player was returned to
1055
1351
  Castle's moderators. The host names the place and session. `{ status: "ok" }`
1056
- or `unavailable`. Hub chrome only.
1352
+ or `unavailable`. Pass `{ block: true }` as a second argument to also block
1353
+ the sender of that stored message. The host asks for confirmation naming the
1354
+ sender; dismissing it, or using a host without confirmation support, reports
1355
+ the message without blocking. Hosts limit confirmation prompts to one per
1356
+ minute; another request during that window reports without blocking. Only `{ status: "ok", blocked: true }`
1357
+ confirms both actions; older hosts can report without confirming a block.
1358
+ Blocks prevent chat between the pair in either direction. Hub chrome only.
1057
1359
  - `Hub.cancel()` gives back an acquisition the deck will not join. Optional: one
1058
1360
  that is never joined expires within two minutes.
1059
1361
  - `Hub.onBack(listener)` hears the host's Back control, which a game cannot hide.
@@ -1444,6 +1746,13 @@ startGame(saved ?? newGame());
1444
1746
  Lifecycle.ready();
1445
1747
  ```
1446
1748
 
1749
+ ## Display
1750
+
1751
+ `getDisplay()` returns a `DeckDisplay`. Its optional `orientation` field is the
1752
+ deck's preferred display orientation: `landscape`, `portrait`, or `any`.
1753
+ Missing or unrecognized preferences mean `any`; read the value as
1754
+ `display.orientation ?? "any"`.
1755
+
1447
1756
  ## Setup
1448
1757
 
1449
1758
  Startup, editor-mode check, and a file-write call for editor UI.
@@ -1586,6 +1895,12 @@ load its assets through the bundler instead.
1586
1895
 
1587
1896
  ## CastleError
1588
1897
 
1898
+ A multiplayer socket closed before its first hello reports its WebSocket close
1899
+ code in `error.extensions.closeCode` when available. Code `4404` means the
1900
+ play proxy could not route the session (`not_running`); it does not prove the
1901
+ runtime ended. A failed hub join cancels its handoff, so retrying a door requires
1902
+ a fresh `Hub.go` acquisition.
1903
+
1589
1904
  Every error the SDK throws is a `CastleError`. Check `code` to tell
1590
1905
  the kinds apart.
1591
1906
 
@@ -1625,3 +1940,22 @@ Common codes:
1625
1940
  that lacks it.
1626
1941
  - `CAULDRON_STORAGE_STALE_GENERATION` — the handle belongs to an older reset
1627
1942
  generation; reopen explicitly rather than replaying work into the new one.
1943
+
1944
+ ### Your games: hub hearts
1945
+
1946
+ `Hub.hearts()` returns `{ status: 'ok', hearts: string[] }` for the signed-in
1947
+ account. `Hub.setHearts(doorIds)` replaces that list with at most eight distinct
1948
+ door ids, oldest first. The host supplies the current deck id; only curated hub
1949
+ places may save hearts. Guests and unavailable hosts return
1950
+ `{ status: 'unavailable', hearts: [] }`; older hosts throw `UNKNOWN_COMMAND`.
1951
+ Invalid lists throw `INVALID_ARGUMENT`, and other host failures use `CastleError`.
1952
+ The dev serve keeps hearts per account in memory until it stops.
1953
+
1954
+ Server hub analytics (hub-game contract v1.93): `session.hub.track(playerId,
1955
+ { kind, subject?, value?, result?, flags? })` sends a numeric event through the
1956
+ server's authenticated platform channel. It returns `Promise<boolean>`: `true`
1957
+ acknowledges queueing, while unsupported hosts and refused delivery return `false`.
1958
+ It never throws. Only opted-in hub bundles are recorded; Ghost stamps the player
1959
+ and town from the session and door pin and excludes the town creator's own plays.
1960
+ The hub-game kit exposes `hub.track(playerId, eventName, properties)` only on
1961
+ places declaring `hub.analytics: true`; see its contract for the numeric vocabulary.
@@ -1,12 +1,16 @@
1
1
  import type { AvatarResult } from "./commands";
2
2
  export type { AvatarResult } from "./commands";
3
3
  export interface CastleAvatarApi {
4
+ /** Present only in an SDK whose Avatar.set carries { color }; the hub-game kit offers colours only when it is here. */
5
+ readonly colors?: true;
4
6
  /**
5
7
  * The player's avatar: their choice, or the default every account has.
6
8
  * `unavailable` for a signed-out visitor, or on a host without avatars.
7
9
  */
8
10
  get(): Promise<AvatarResult>;
9
- /** Choose the avatar this player wears everywhere from now on. */
10
- set(avatar: number): Promise<AvatarResult>;
11
+ /** Choose the avatar, and optionally its colour, worn everywhere. Requires a host with colours for options.color. */
12
+ set(avatar: number, options?: {
13
+ color?: number;
14
+ }): Promise<AvatarResult>;
11
15
  }
12
16
  export declare const Avatar: CastleAvatarApi;
@@ -1,17 +1,17 @@
1
1
  // Avatar — the player's platform avatar (cauldron-game-server docs/HUB.md,
2
2
  // decision 4): one per account, worn in every hub place. v1 is an index into the
3
- // hub-game kit's character templates; there is no editor and no cosmetics.
3
+ // hub-game kit's character templates, with optional colour choices.
4
4
  //
5
5
  // The hub-game kit is the one caller: it reads the avatar to dress the player
6
6
  // and offers the choice in its picker. Other players' avatars are not read
7
7
  // here; a place's server learns them from ghost.
8
8
  import { CastleError } from "./errors";
9
9
  import { hostRequest } from "./transport";
10
- export const Avatar = { get, set };
10
+ export const Avatar = { get, set, colors: true };
11
11
  async function get() {
12
12
  return hostRequest("avatar.get", {});
13
13
  }
14
- async function set(avatar) {
14
+ async function set(avatar, options) {
15
15
  if (typeof avatar !== "number" || !Number.isInteger(avatar) || avatar < 0) {
16
16
  throw new CastleError({
17
17
  code: "INVALID_ARGUMENT",
@@ -19,5 +19,13 @@ async function set(avatar) {
19
19
  operation: "Avatar.set",
20
20
  });
21
21
  }
22
- return hostRequest("avatar.set", { avatar });
22
+ const color = options?.color;
23
+ if (color !== undefined && (!Number.isInteger(color) || color < 0)) {
24
+ throw new CastleError({
25
+ code: "INVALID_ARGUMENT",
26
+ message: "Avatar.set requires a non-negative integer colour.",
27
+ operation: "Avatar.set",
28
+ });
29
+ }
30
+ return hostRequest("avatar.set", color === undefined ? { avatar } : { avatar, color });
23
31
  }
@@ -13,7 +13,11 @@ export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckF
13
13
  export { Haptics } from "./haptics";
14
14
  export type { CastleHapticsApi, HapticsResult, HapticsStatus, HapticStyle } from "./haptics";
15
15
  export { Hub } from "./hub";
16
- export type { CastleHubApi, HubBackResult, HubCancelResult, HubCancelStatus, HubChatMessage, HubChatResult, HubDoor, HubDoorsResult, HubFriend, HubFriendsResult, HubGoParams, HubGoResult, HubHandoffResult, HubHandoffStatus, HubJumpResult, HubPlacementKind, HubReportResult, HubSayResult, } from "./hub";
16
+ export type { CastleHubApi, HubBackResult, HubCancelResult, HubCancelStatus, HubChatMessage, HubChatResult, HubDoor, HubDoorsResult, HubFriend, HubFriendsResult, HubInviteResult, HubCanInviteResult, HubInviteArrivalResult, HubHeartsResult, HubGoParams, HubSignInParams, HubSignInResult, HubGoResult, HubHandoffResult, HubHandoffStatus, HubJumpResult, HubPlacementKind, HubReportResult, HubSayResult, } from "./hub";
17
+ export { Social } from "./social";
18
+ export type { CastleSocialApi, SocialFriend, SocialPresence } from "./social";
19
+ export { Party } from "./party";
20
+ export type { CastlePartyApi, PartyMember, PartyMessage, PartyMessagesResult, PartyStatus, PartySummary, } from "./party";
17
21
  export { Leaderboard } from "./leaderboard";
18
22
  export type { LeaderboardData, LeaderboardEntry, LeaderboardOptions, LeaderboardScope, LeaderboardShowOptions, LeaderboardShowResult, LeaderboardShowStatus, LeaderboardSort, } from "./leaderboard";
19
23
  export { Lifecycle } from "./lifecycle";
@@ -35,7 +39,7 @@ export type { CastlePortalApi, PortalOpenResult, PortalOpenStatus, PortalPrefetc
35
39
  export { CARD_RATIO, deleteFile, fileUrl, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, openFile, renameFile, requestReload, setup, takeReloadState, writeFileOnce, } from "./runtime";
36
40
  export type { FileChange, FilesChangedEvent } from "./runtime";
37
41
  export { cardUnit, fitStage, fovForAspect, getDisplay } from "./display";
38
- export type { DeckDisplay, DeckLayout } from "./display";
42
+ export type { DeckDisplay, DeckLayout, DeckOrientation } from "./display";
39
43
  export { flushSaves, hasPendingSave, onSaveState, writeFile, } from "./saveQueue";
40
44
  export type { SaveState } from "./saveQueue";
41
45
  export { SharedStorage, Storage } from "./storage";
@@ -49,4 +53,4 @@ export type { CastleUser, CastleUserApi } from "./user";
49
53
  export { createSaveCoordinator } from "./saveCoordinator";
50
54
  export type { CoordinatedChange, CoordinatedSave, SaveCoordinator, SaveStatus, } from "./saveCoordinator";
51
55
  export { SaveError } from "./save";
52
- 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";
56
+ export type { SaveApi, SaveBucketApi, SaveBucketRead, SaveChange, SaveCheck, SaveConditionalCheck, SaveConditionalWriteInput, SaveClaimed, SaveClaimInput, SaveErrorEnvelope, SaveInitial, SaveInitializeInput, SaveOpened, SaveOperation, SaveReadTarget, SaveReceipt, SaveRecentOperationsInput, SaveRecentOperationsPage, SaveRevision, SaveRows, SaveScope, SaveSelection, SaveSnapshot, SaveTarget, SaveTransactionInput, SaveWriter, } from "./save";
@@ -9,6 +9,8 @@ export { experiment, experiments, experimentsReady } from "./experiments";
9
9
  export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckFile, } from "./files";
10
10
  export { Haptics } from "./haptics";
11
11
  export { Hub } from "./hub";
12
+ export { Social } from "./social";
13
+ export { Party } from "./party";
12
14
  export { Leaderboard } from "./leaderboard";
13
15
  export { Lifecycle } from "./lifecycle";
14
16
  export { Multiplayer } from "./multiplayer";