castle-web-cli 0.4.239 → 0.4.241

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 (396) hide show
  1. package/dist/agent.js +5 -1
  2. package/dist/api.d.ts +20 -0
  3. package/dist/api.js +57 -0
  4. package/dist/bundle.d.ts +38 -1
  5. package/dist/bundle.js +309 -13
  6. package/dist/castle-host/host.js +163 -11
  7. package/dist/castleJson.d.ts +10 -0
  8. package/dist/castleJson.js +46 -2
  9. package/dist/check.js +5 -2
  10. package/dist/devSessionServer.js +4 -1
  11. package/dist/devSessionStorage.d.ts +1 -0
  12. package/dist/devSessionStorage.js +32 -7
  13. package/dist/importOrder.d.ts +2 -0
  14. package/dist/importOrder.js +29 -0
  15. package/dist/index.js +6 -3
  16. package/dist/init.js +24 -2
  17. package/dist/multiplayerDoc.d.ts +1 -1
  18. package/dist/multiplayerDoc.js +2 -0
  19. package/dist/platformDoc.js +3 -2
  20. package/dist/playPagePolicy.js +5 -1
  21. package/dist/resetLeaderboards.d.ts +8 -1
  22. package/dist/resetLeaderboards.js +43 -8
  23. package/dist/roomLogs.d.ts +1 -0
  24. package/dist/roomLogs.js +30 -6
  25. package/dist/save-deck.d.ts +32 -2
  26. package/dist/save-deck.js +240 -39
  27. package/kits/base/CLAUDE.md +1 -1
  28. package/kits/base/castle.json +1 -1
  29. package/kits/base/sdk/README.md +174 -6
  30. package/kits/base/sdk/analytics.d.ts +8 -0
  31. package/kits/base/sdk/analytics.js +92 -0
  32. package/kits/base/sdk/castle.d.ts +5 -1
  33. package/kits/base/sdk/castle.js +2 -0
  34. package/kits/base/sdk/commands.d.ts +48 -0
  35. package/kits/base/sdk/commands.js +1 -0
  36. package/kits/base/sdk/debugConsole.d.ts +17 -0
  37. package/kits/base/sdk/debugConsole.js +154 -0
  38. package/kits/base/sdk/experiments.js +24 -1
  39. package/kits/base/sdk/hostRetry.d.ts +7 -0
  40. package/kits/base/sdk/hostRetry.js +57 -0
  41. package/kits/base/sdk/hub.d.ts +20 -2
  42. package/kits/base/sdk/hub.js +99 -13
  43. package/kits/base/sdk/multiplayer.d.ts +2 -0
  44. package/kits/base/sdk/multiplayer.js +168 -26
  45. package/kits/base/sdk/reconnectBudget.d.ts +6 -0
  46. package/kits/base/sdk/reconnectBudget.js +41 -1
  47. package/kits/base/sdk/runtime.js +36 -19
  48. package/kits/base/sdk/server/hub.d.ts +19 -0
  49. package/kits/base/sdk/server/hub.js +12 -0
  50. package/kits/base/sdk/server/platformHandle.d.ts +1 -0
  51. package/kits/base/sdk/server/wrapper.d.ts +1 -1
  52. package/kits/base/sdk/server/wrapper.js +26 -1
  53. package/kits/base/sdk/transport.d.ts +2 -1
  54. package/kits/base/sdk/transport.js +35 -0
  55. package/kits/hub-game/CLAUDE.md +66 -19
  56. package/kits/hub-game/code/client/act.js +9 -6
  57. package/kits/hub-game/code/client/actCore.js +26 -6
  58. package/kits/hub-game/code/client/actGateLog.js +36 -0
  59. package/kits/hub-game/code/client/actionOverflow.js +29 -8
  60. package/kits/hub-game/code/client/actionRailSurface.js +186 -0
  61. package/kits/hub-game/code/client/actionRailTree.js +173 -0
  62. package/kits/hub-game/code/client/askSurface.js +85 -0
  63. package/kits/hub-game/code/client/askTree.js +51 -0
  64. package/kits/hub-game/code/client/attention.js +31 -6
  65. package/kits/hub-game/code/client/ballot.js +42 -5
  66. package/kits/hub-game/code/client/ballotSurface.js +115 -0
  67. package/kits/hub-game/code/client/ballotTree.js +180 -0
  68. package/kits/hub-game/code/client/catchingUp.js +19 -0
  69. package/kits/hub-game/code/client/celebrate.js +66 -0
  70. package/kits/hub-game/code/client/chrome.js +481 -57
  71. package/kits/hub-game/code/client/companion.js +93 -23
  72. package/kits/hub-game/code/client/companionDress.js +1 -1
  73. package/kits/hub-game/code/client/cornerSurface.js +106 -0
  74. package/kits/hub-game/code/client/cornerTree.js +83 -0
  75. package/kits/hub-game/code/client/decor.js +20 -11
  76. package/kits/hub-game/code/client/deviceStorage.js +121 -0
  77. package/kits/hub-game/code/client/disguise.js +23 -0
  78. package/kits/hub-game/code/client/disguiseDraw.js +87 -0
  79. package/kits/hub-game/code/client/dockSurface.js +206 -0
  80. package/kits/hub-game/code/client/dockTree.js +232 -0
  81. package/kits/hub-game/code/client/earned.js +29 -0
  82. package/kits/hub-game/code/client/emoteSurface.js +188 -0
  83. package/kits/hub-game/code/client/emoteTree.js +264 -0
  84. package/kits/hub-game/code/client/farAvatars.js +4 -3
  85. package/kits/hub-game/code/client/fpsTelemetry.js +3 -1
  86. package/kits/hub-game/code/client/grab.js +121 -50
  87. package/kits/hub-game/code/client/holdShow.js +19 -0
  88. package/kits/hub-game/code/client/hookLayer.js +96 -12
  89. package/kits/hub-game/code/client/hubControls.js +7 -1
  90. package/kits/hub-game/code/client/hudSurface.js +11 -3
  91. package/kits/hub-game/code/client/hudTree.js +7 -4
  92. package/kits/hub-game/code/client/idle.js +21 -3
  93. package/kits/hub-game/code/client/invites.js +24 -3
  94. package/kits/hub-game/code/client/keys.js +15 -0
  95. package/kits/hub-game/code/client/labelsNear.js +8 -1
  96. package/kits/hub-game/code/client/layoutCache.js +57 -8
  97. package/kits/hub-game/code/client/loadingCover.js +53 -4
  98. package/kits/hub-game/code/client/menuIcons.js +15 -0
  99. package/kits/hub-game/code/client/menuSurface.js +102 -0
  100. package/kits/hub-game/code/client/menuTree.js +135 -0
  101. package/kits/hub-game/code/client/modelLook.js +41 -0
  102. package/kits/hub-game/code/client/padCues.js +11 -7
  103. package/kits/hub-game/code/client/padReadability.js +3 -3
  104. package/kits/hub-game/code/client/pickerSurface.js +152 -0
  105. package/kits/hub-game/code/client/pickerTree.js +163 -0
  106. package/kits/hub-game/code/client/pushVisit.js +4 -2
  107. package/kits/hub-game/code/client/quality.js +188 -29
  108. package/kits/hub-game/code/client/qualityEntry.js +10 -1
  109. package/kits/hub-game/code/client/quickChatSurface.js +222 -0
  110. package/kits/hub-game/code/client/quickChatTree.js +201 -0
  111. package/kits/hub-game/code/client/rehello.js +75 -0
  112. package/kits/hub-game/code/client/renderVisibility.js +17 -0
  113. package/kits/hub-game/code/client/replay.js +118 -0
  114. package/kits/hub-game/code/client/role.js +3 -0
  115. package/kits/hub-game/code/client/safeLayout.js +441 -56
  116. package/kits/hub-game/code/client/safeStyle.js +13 -10
  117. package/kits/hub-game/code/client/say.js +2 -0
  118. package/kits/hub-game/code/client/soundSurface.js +77 -0
  119. package/kits/hub-game/code/client/soundTree.js +74 -0
  120. package/kits/hub-game/code/client/soundscape.js +12 -9
  121. package/kits/hub-game/code/client/soundscapeCues.js +1 -1
  122. package/kits/hub-game/code/client/state.js +67 -1
  123. package/kits/hub-game/code/client/stuckSurface.js +76 -0
  124. package/kits/hub-game/code/client/stuckTree.js +67 -0
  125. package/kits/hub-game/code/client/talk.js +42 -12
  126. package/kits/hub-game/code/client/talkTree.js +4 -2
  127. package/kits/hub-game/code/client/textAskSurface.js +147 -0
  128. package/kits/hub-game/code/client/textAskTree.js +67 -0
  129. package/kits/hub-game/code/client/tiers.js +252 -27
  130. package/kits/hub-game/code/client/together.js +4 -1
  131. package/kits/hub-game/code/client/uiDom.js +86 -8
  132. package/kits/hub-game/code/client/uiTree.js +33 -4
  133. package/kits/hub-game/code/client/vehicle.js +72 -51
  134. package/kits/hub-game/code/client/weakestTier.js +75 -31
  135. package/kits/hub-game/code/client/wear.js +159 -5
  136. package/kits/hub-game/code/client/worldLabels.js +205 -25
  137. package/kits/hub-game/code/companionSpec.js +4 -2
  138. package/kits/hub-game/code/server/act.js +3 -0
  139. package/kits/hub-game/code/server/actGate.js +83 -0
  140. package/kits/hub-game/code/server/actions.js +71 -15
  141. package/kits/hub-game/code/server/actors.js +20 -5
  142. package/kits/hub-game/code/server/analytics.js +35 -3
  143. package/kits/hub-game/code/server/ask.js +39 -3
  144. package/kits/hub-game/code/server/ballot.js +167 -4
  145. package/kits/hub-game/code/server/celebrate.js +64 -0
  146. package/kits/hub-game/code/server/companion.js +17 -2
  147. package/kits/hub-game/code/server/decor.js +11 -2
  148. package/kits/hub-game/code/server/disguise.js +63 -0
  149. package/kits/hub-game/code/server/earned.js +6 -2
  150. package/kits/hub-game/code/server/friendBests.js +13 -4
  151. package/kits/hub-game/code/server/friendsAmong.js +67 -8
  152. package/kits/hub-game/code/server/grab.js +12 -2
  153. package/kits/hub-game/code/server/heldOffers.js +142 -0
  154. package/kits/hub-game/code/server/holdShow.js +98 -0
  155. package/kits/hub-game/code/server/hub.js +991 -72
  156. package/kits/hub-game/code/server/idle.js +110 -9
  157. package/kits/hub-game/code/server/index.js +9 -0
  158. package/kits/hub-game/code/server/labels.js +13 -3
  159. package/kits/hub-game/code/server/manifest.js +94 -6
  160. package/kits/hub-game/code/server/menu.js +26 -3
  161. package/kits/hub-game/code/server/npcs.js +55 -9
  162. package/kits/hub-game/code/server/observe.js +67 -6
  163. package/kits/hub-game/code/server/players.js +14 -2
  164. package/kits/hub-game/code/server/replay.js +135 -0
  165. package/kits/hub-game/code/server/standing.js +7 -3
  166. package/kits/hub-game/code/server/storageLimit.js +4 -1
  167. package/kits/hub-game/code/server/townDay.js +74 -0
  168. package/kits/hub-game/code/server/vehicle.js +3 -0
  169. package/kits/hub-game/code/server/vis.js +26 -4
  170. package/kits/hub-game/code/server/wallet.js +677 -0
  171. package/kits/hub-game/code/server/wear.js +13 -3
  172. package/kits/hub-game/code/server/writerLease.js +191 -0
  173. package/kits/hub-game/code/shared/act.js +1 -1
  174. package/kits/hub-game/code/shared/expression.js +6 -0
  175. package/kits/hub-game/code/shared/replay.js +37 -0
  176. package/kits/hub-game/code/systems/hub.js +429 -55
  177. package/kits/hub-game/docs/analytics.md +16 -2
  178. package/kits/hub-game/docs/contract.md +956 -101
  179. package/kits/hub-game/docs/home-pieces.md +5 -6
  180. package/kits/hub-game/docs/observed-progress.md +49 -1
  181. package/kits/hub-game/docs/vehicle-preset.md +23 -0
  182. package/kits/hub-game/index.html +1 -0
  183. package/kits/hub-game/models/hats/baker-cap.pxmodel +3 -3
  184. package/kits/hub-game/models/hats/bat-clip.pxmodel +3 -3
  185. package/kits/hub-game/models/hats/beekeeper.pxmodel +3 -3
  186. package/kits/hub-game/models/hats/cap.pxmodel +3 -3
  187. package/kits/hub-game/models/hats/captain.pxmodel +3 -3
  188. package/kits/hub-game/models/hats/chef-toque.pxmodel +3 -3
  189. package/kits/hub-game/models/hats/crooked-top.pxmodel +3 -3
  190. package/kits/hub-game/models/hats/delivery-cap.pxmodel +3 -3
  191. package/kits/hub-game/models/hats/fire-helmet.pxmodel +3 -3
  192. package/kits/hub-game/models/hats/flower-crown.pxmodel +3 -3
  193. package/kits/hub-game/models/hats/foam-crown.pxmodel +3 -3
  194. package/kits/hub-game/models/hats/hard-hat.pxmodel +3 -3
  195. package/kits/hub-game/models/hats/lantern.pxmodel +3 -3
  196. package/kits/hub-game/models/hats/laurel.pxmodel +3 -3
  197. package/kits/hub-game/models/hats/lighthouse.pxmodel +3 -3
  198. package/kits/hub-game/models/hats/nurse-cap.pxmodel +3 -3
  199. package/kits/hub-game/models/hats/police-cap.pxmodel +3 -3
  200. package/kits/hub-game/models/hats/sailor.pxmodel +3 -3
  201. package/kits/hub-game/models/hats/souwester.pxmodel +3 -3
  202. package/kits/hub-game/models/hats/straw.pxmodel +3 -3
  203. package/kits/hub-game/models/hats/sunflower.pxmodel +3 -3
  204. package/kits/hub-game/models/hats/sweatband.pxmodel +3 -3
  205. package/kits/hub-game/models/hats/teacher-beret.pxmodel +3 -3
  206. package/kits/hub-game/models/hats/witch.pxmodel +3 -3
  207. package/kits/hub-game/models/hold-show/daisy.pxmodel +231 -0
  208. package/kits/hub-game/models/hold-show/moonflower.pxmodel +171 -0
  209. package/kits/hub-game/models/hold-show/rose.pxmodel +191 -0
  210. package/kits/hub-game/models/hold-show/square/daisy.pxmodel +233 -0
  211. package/kits/hub-game/models/hold-show/square/moonflower.pxmodel +173 -0
  212. package/kits/hub-game/models/hold-show/square/rose.pxmodel +193 -0
  213. package/kits/hub-game/models/hold-show/square/sunflower.pxmodel +313 -0
  214. package/kits/hub-game/models/hold-show/square/tulip.pxmodel +133 -0
  215. package/kits/hub-game/models/hold-show/sunflower.pxmodel +311 -0
  216. package/kits/hub-game/models/hold-show/tulip.pxmodel +131 -0
  217. package/kits/hub-game/package-lock.json +3 -3
  218. package/kits/hub-game/package.json +4 -3
  219. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +1 -0
  220. package/kits/hub-game/scripts/fixtures/hud-surface.json +12 -12
  221. package/kits/hub-game/scripts/fixtures/talk-surface.json +8 -8
  222. package/kits/hub-game/scripts/gen-hats.mjs +1 -1
  223. package/kits/hub-game/scripts/gen-hold-show.mjs +27 -0
  224. package/kits/hub-game/scripts/pack.mjs +89 -23
  225. package/kits/hub-game/scripts/test-act-client.mjs +5 -0
  226. package/kits/hub-game/scripts/test-act-core.mjs +32 -0
  227. package/kits/hub-game/scripts/test-act-gate.mjs +186 -0
  228. package/kits/hub-game/scripts/test-action-rail-crowded-dom.mjs +7 -1
  229. package/kits/hub-game/scripts/test-action-rail-default-dom.mjs +102 -0
  230. package/kits/hub-game/scripts/test-action-rail-never-silent-dom.mjs +50 -0
  231. package/kits/hub-game/scripts/test-action-rail-surface.mjs +368 -0
  232. package/kits/hub-game/scripts/test-action-rail-town-jobs-dom.mjs +118 -0
  233. package/kits/hub-game/scripts/test-actions-client.mjs +5 -3
  234. package/kits/hub-game/scripts/test-actions.mjs +24 -0
  235. package/kits/hub-game/scripts/test-actors.mjs +19 -0
  236. package/kits/hub-game/scripts/test-again-corner-dom.mjs +59 -0
  237. package/kits/hub-game/scripts/test-analytics.mjs +79 -0
  238. package/kits/hub-game/scripts/test-arrival-pose-server.mjs +25 -8
  239. package/kits/hub-game/scripts/test-ask-client.mjs +9 -0
  240. package/kits/hub-game/scripts/test-ask-surface.mjs +188 -0
  241. package/kits/hub-game/scripts/test-attention.mjs +43 -1
  242. package/kits/hub-game/scripts/test-ballot-sheet-dom.mjs +71 -0
  243. package/kits/hub-game/scripts/test-ballot-surface.mjs +276 -0
  244. package/kits/hub-game/scripts/test-ballot.mjs +421 -4
  245. package/kits/hub-game/scripts/test-ban-join.mjs +1 -1
  246. package/kits/hub-game/scripts/test-celebrate-client.mjs +62 -0
  247. package/kits/hub-game/scripts/test-celebrate.mjs +116 -0
  248. package/kits/hub-game/scripts/test-chat.mjs +73 -0
  249. package/kits/hub-game/scripts/test-companion-client.mjs +203 -21
  250. package/kits/hub-game/scripts/test-companion.mjs +110 -3
  251. package/kits/hub-game/scripts/test-control-layout-dom.mjs +57 -10
  252. package/kits/hub-game/scripts/test-corner-surface.mjs +268 -0
  253. package/kits/hub-game/scripts/test-decor-client.mjs +59 -3
  254. package/kits/hub-game/scripts/test-decor.mjs +27 -0
  255. package/kits/hub-game/scripts/test-device-class.mjs +4 -1
  256. package/kits/hub-game/scripts/test-disguise-client.mjs +281 -0
  257. package/kits/hub-game/scripts/test-disguise.mjs +176 -0
  258. package/kits/hub-game/scripts/test-dock-surface.mjs +404 -0
  259. package/kits/hub-game/scripts/test-door-stay-client.mjs +602 -0
  260. package/kits/hub-game/scripts/test-door-stay.mjs +613 -0
  261. package/kits/hub-game/scripts/test-earned-client.mjs +119 -0
  262. package/kits/hub-game/scripts/test-emote-surface.mjs +616 -0
  263. package/kits/hub-game/scripts/test-fps-telemetry.mjs +39 -4
  264. package/kits/hub-game/scripts/test-friend-bests.mjs +38 -12
  265. package/kits/hub-game/scripts/test-ghost-click-dom.mjs +75 -0
  266. package/kits/hub-game/scripts/test-grab-client.mjs +29 -2
  267. package/kits/hub-game/scripts/test-grab-orbit.mjs +260 -11
  268. package/kits/hub-game/scripts/test-grab.mjs +10 -1
  269. package/kits/hub-game/scripts/test-hats.mjs +28 -0
  270. package/kits/hub-game/scripts/test-held-offers.mjs +394 -0
  271. package/kits/hub-game/scripts/test-high-only.mjs +3 -3
  272. package/kits/hub-game/scripts/test-hold-show-client.mjs +175 -0
  273. package/kits/hub-game/scripts/test-hold-show.mjs +355 -0
  274. package/kits/hub-game/scripts/test-hub-controls.mjs +3 -1
  275. package/kits/hub-game/scripts/test-hub-idle.mjs +348 -0
  276. package/kits/hub-game/scripts/test-hub-leaving.mjs +21 -0
  277. package/kits/hub-game/scripts/test-hub-ops.mjs +119 -0
  278. package/kits/hub-game/scripts/test-hub-trip.mjs +240 -4
  279. package/kits/hub-game/scripts/test-hud-clear.mjs +83 -0
  280. package/kits/hub-game/scripts/test-hud-rate.mjs +2 -1
  281. package/kits/hub-game/scripts/test-idle.mjs +160 -0
  282. package/kits/hub-game/scripts/test-invites-client.mjs +53 -0
  283. package/kits/hub-game/scripts/test-labels.mjs +11 -0
  284. package/kits/hub-game/scripts/test-landscape-layout.mjs +20 -0
  285. package/kits/hub-game/scripts/test-loading-cover.mjs +67 -1
  286. package/kits/hub-game/scripts/test-manifest.mjs +27 -0
  287. package/kits/hub-game/scripts/test-menu-client.mjs +54 -5
  288. package/kits/hub-game/scripts/test-menu-surface.mjs +236 -0
  289. package/kits/hub-game/scripts/test-npcs.mjs +128 -0
  290. package/kits/hub-game/scripts/test-observed.mjs +171 -3
  291. package/kits/hub-game/scripts/test-pack.mjs +166 -0
  292. package/kits/hub-game/scripts/test-pad-cues.mjs +39 -0
  293. package/kits/hub-game/scripts/test-picker-surface.mjs +321 -0
  294. package/kits/hub-game/scripts/test-placeat-server.mjs +648 -0
  295. package/kits/hub-game/scripts/test-placement-cache.mjs +1 -1
  296. package/kits/hub-game/scripts/test-pointer-clear-dom.mjs +82 -0
  297. package/kits/hub-game/scripts/test-progress-reset.mjs +184 -6
  298. package/kits/hub-game/scripts/test-push-visit.mjs +9 -0
  299. package/kits/hub-game/scripts/test-quality.mjs +312 -9
  300. package/kits/hub-game/scripts/test-quick-chat-surface.mjs +511 -0
  301. package/kits/hub-game/scripts/test-rehello.mjs +242 -3
  302. package/kits/hub-game/scripts/test-rejoin-yaw.mjs +138 -0
  303. package/kits/hub-game/scripts/test-relations-among.mjs +13 -7
  304. package/kits/hub-game/scripts/test-relations-refresh.mjs +90 -2
  305. package/kits/hub-game/scripts/test-replay-client.mjs +110 -0
  306. package/kits/hub-game/scripts/test-replay.mjs +178 -0
  307. package/kits/hub-game/scripts/test-resume-held.mjs +13 -0
  308. package/kits/hub-game/scripts/test-resume-pose-server.mjs +43 -5
  309. package/kits/hub-game/scripts/test-role-client.mjs +2 -1
  310. package/kits/hub-game/scripts/test-safe-act.mjs +233 -0
  311. package/kits/hub-game/scripts/test-safe-caption.mjs +364 -0
  312. package/kits/hub-game/scripts/test-safe-layout.mjs +79 -0
  313. package/kits/hub-game/scripts/test-safe-prompt.mjs +163 -0
  314. package/kits/hub-game/scripts/test-sound-surface.mjs +256 -0
  315. package/kits/hub-game/scripts/test-soundscape.mjs +85 -2
  316. package/kits/hub-game/scripts/test-standing.mjs +135 -2
  317. package/kits/hub-game/scripts/test-stuck-surface.mjs +174 -0
  318. package/kits/hub-game/scripts/test-stuck.mjs +36 -1
  319. package/kits/hub-game/scripts/test-talk-surface.mjs +23 -6
  320. package/kits/hub-game/scripts/test-talk-walk-dom.mjs +123 -0
  321. package/kits/hub-game/scripts/test-text-ask-surface.mjs +273 -0
  322. package/kits/hub-game/scripts/test-tiers.mjs +453 -3
  323. package/kits/hub-game/scripts/test-toast-no-row-dom.mjs +71 -0
  324. package/kits/hub-game/scripts/test-together.mjs +11 -0
  325. package/kits/hub-game/scripts/test-town-day.mjs +90 -0
  326. package/kits/hub-game/scripts/test-try-on.mjs +39 -0
  327. package/kits/hub-game/scripts/test-ui-dom-dom.mjs +49 -2
  328. package/kits/hub-game/scripts/test-ui-tree.mjs +28 -0
  329. package/kits/hub-game/scripts/test-vehicle-client.mjs +68 -1
  330. package/kits/hub-game/scripts/test-vis.mjs +145 -0
  331. package/kits/hub-game/scripts/test-wallet.mjs +650 -0
  332. package/kits/hub-game/scripts/test-weakest-tier.mjs +135 -1
  333. package/kits/hub-game/scripts/test-world-labels.mjs +340 -0
  334. package/kits/hub-game/scripts/test-writer-lease-server.mjs +234 -0
  335. package/kits/hub-game/scripts/test-writer-lease.mjs +281 -0
  336. package/kits/hub-game/scripts/writer-storage-fixture.mjs +37 -0
  337. package/kits/hub-game/tools/hubScene/export.mjs +6 -5
  338. package/kits/hub-game/tools/hubScene/hubdata.mjs +10 -0
  339. package/kits/hub-game/tools/hubScene/test/export-fixture.mjs +36 -2
  340. package/kits/hub-game/tools/hubScene/validate-manifest.mjs +10 -2
  341. package/kits/multiplayer-3d/castle.json +5 -5
  342. package/kits/multiplayer-3d/code/client/resumeGate.js +66 -2
  343. package/kits/multiplayer-3d/code/server/ownership.js +25 -6
  344. package/kits/multiplayer-3d/code/server/world.js +19 -4
  345. package/kits/multiplayer-3d/code/systems/multiplayer.js +108 -18
  346. package/kits/multiplayer-3d/package-lock.json +1 -1
  347. package/kits/multiplayer-3d/package.json +2 -1
  348. package/kits/multiplayer-3d/scripts/test-ground-half.mjs +56 -0
  349. package/kits/multiplayer-3d/scripts/test-join-watchdog.mjs +54 -3
  350. package/kits/multiplayer-3d/scripts/test-owned-moves.mjs +190 -0
  351. package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +417 -5
  352. package/kits/multiplayer-3d/scripts/test-resync-reconnect.mjs +68 -0
  353. package/kits/physics-2d/castle.json +2 -2
  354. package/kits/physics-2d/engine/scene.js +10 -2
  355. package/kits/physics-3d/CLAUDE.md +14 -0
  356. package/kits/physics-3d/behaviors/Player.jsx +39 -3
  357. package/kits/physics-3d/castle.json +3 -3
  358. package/kits/physics-3d/docs/engine-model-cache.md +109 -0
  359. package/kits/physics-3d/docs/engine-player.md +76 -0
  360. package/kits/physics-3d/docs/engine-skip-work.md +16 -0
  361. package/kits/physics-3d/docs/pxmodel-format.md +5 -1
  362. package/kits/physics-3d/engine3d/gait.js +16 -8
  363. package/kits/physics-3d/engine3d/groundsize.js +23 -0
  364. package/kits/physics-3d/engine3d/kithooks.js +50 -0
  365. package/kits/physics-3d/engine3d/look.js +110 -17
  366. package/kits/physics-3d/engine3d/lookbake.js +19 -1
  367. package/kits/physics-3d/engine3d/materialpresets.js +3 -2
  368. package/kits/physics-3d/engine3d/modelcache.js +280 -0
  369. package/kits/physics-3d/engine3d/modelcachedigest.js +37 -0
  370. package/kits/physics-3d/engine3d/modelcachegate.js +69 -0
  371. package/kits/physics-3d/engine3d/modelrefs.js +13 -0
  372. package/kits/physics-3d/engine3d/optimize.js +20 -9
  373. package/kits/physics-3d/engine3d/playerRun.js +26 -1
  374. package/kits/physics-3d/engine3d/pxmodel.js +7 -3
  375. package/kits/physics-3d/engine3d/templatecache.js +722 -0
  376. package/kits/physics-3d/engine3d/world3d.js +211 -17
  377. package/kits/physics-3d/package-lock.json +1 -1
  378. package/kits/physics-3d/package.json +2 -1
  379. package/kits/physics-3d/play/behaviors/Player.js +43 -3
  380. package/kits/physics-3d/scripts/render.mjs +56 -8
  381. package/kits/physics-3d/scripts/template-cache-fixtures.mjs +37 -0
  382. package/kits/physics-3d/scripts/template-cache-v1-bytes.json +49 -0
  383. package/kits/physics-3d/scripts/test-coaxial-escape.mjs +176 -0
  384. package/kits/physics-3d/scripts/test-gait.mjs +53 -9
  385. package/kits/physics-3d/scripts/test-ground-half.mjs +120 -0
  386. package/kits/physics-3d/scripts/test-model-cache.mjs +600 -0
  387. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +1 -0
  388. package/kits/physics-3d/scripts/test-sleeping-models.mjs +384 -0
  389. package/kits/physics-3d/scripts/test-template-cache-minified.mjs +106 -0
  390. package/kits/physics-3d/scripts/test-template-cache.mjs +519 -0
  391. package/kits/physics-3d/scripts/test-wall-slide.mjs +272 -0
  392. package/kits/physics-3d/systems/physics3d.js +59 -2
  393. package/kits/real-time/castle.json +2 -2
  394. package/kits/real-time/code/client/connection.js +3 -0
  395. package/package.json +2 -2
  396. package/vendor/three/examples/jsm/libs/fflate.module.js +2672 -0
@@ -1 +1 @@
1
- export declare const MULTIPLAYER_DOC = "# Multiplayer, in practice\n\nRead this before writing or changing a server entry or client netcode by hand.\nWritten fresh by the Castle CLI at every serve start; the full API reference is\nthe SDK's own, at `imports/castle.base/sdk/README.md`.\n\n## Reach for a kit first\n\n`castle.multiplayer-2d` and `castle.multiplayer-3d` (both on `castle.real-time`)\nalready do everything below: a server-authoritative world, one snapshot per\ntick, pose interpolation, roster handling, reconnects, ownership of loose\nobjects. `castle.turn-based` does the same for games played in turns, with\nseats, spectators and idle clearing. A deck on one of those kits normally\nwrites nothing against the raw session API, and the right move is usually to\nadd a rule to the deck's own game hooks rather than a message of your own.\n\nHand-roll only when the game genuinely does not fit them -- and then keep the\nshape below, because it is the shape the platform's limits ask for.\n\n## The outbound budget\n\nA session may send about `40 + 40 x connected players` frames per second, with\nroughly two seconds of burst, and about 1 MiB/s of bytes. What a frame costs:\n\n| call | frames |\n|---|---|\n| `session.send(playerId, data)` | 1 |\n| `session.broadcast(data)` | 1, whatever the player count |\n| `session.broadcast(data, { except })` | one per recipient -- it is a loop of sends |\n\nFrames over the budget are **dropped silently**. The session keeps running and\na dropped frame is never retried, so the symptom is not an error: it is a\nclient whose world quietly stops matching everyone else's. Only sustained abuse\nat several times the budget ends a session.\n\nThe arithmetic that matters, at `tickRate: 20`:\n\n- 4 players, one `send` per player per tick: 80 frames/s of a 200 budget --\n before a single hit, join, chat or one-off frame.\n- 8 players, same: 160 of 360. A second per-player message per tick makes it\n 320, and at `tickRate: 30` that is 480 -- over, and frames start dropping.\n- Either, with one `broadcast` per tick: 20 frames/s. The budget stops being\n something you have to think about.\n\nPer-player sends also send the same bytes N times toward the byte budget. The\nlocal serve does not drop anything, but it warns when a 1-second window goes\nover -- `[multiplayer] server sent ...` in `.castle/logs.txt` and in the serve's\nown output (`.castle/serve.log` when it was detached).\n\n## The snapshot pattern\n\nAuthoritative state lives on the server. `onTick` builds ONE snapshot of every\nplayer and broadcasts it once.\n\nEvery client reads EVERY entry in that snapshot, **including its own** -- the\ndifference is only what it does with each:\n\n- **Other players' entries** drive what it draws for them (interpolated between\n snapshots), and are how it learns someone left or went silent.\n- **Its own entry** is the server's verdict on itself. Take hp, alive/wrecked,\n kills, score and the match state from it every tick, exactly as if it were\n someone else's. The one field it does NOT overwrite each tick is its own pose:\n the local player moves on its own input so the game stays responsive, and the\n client only snaps to the server's position when the two have drifted far\n apart. Ignoring the rest of its own entry is how a player ends up alive on\n their own screen and dead on everyone else's.\n\n```js\nconst state = { matchNumber: 1, players: {}, parked: new Map() };\n\nexport default {\n onPlayerJoin(session, player) {\n state.players[player.playerId] = { x: 0, y: 0, hp: 100, kills: 0, alive: true };\n },\n onMessage(session, player, data) {\n if (data.t === 'move') applyMove(state.players[player.playerId], data);\n },\n onTick(session) {\n // One frame per tick, for any number of players.\n session.broadcast({ t: 'snap', n: state.matchNumber, players: state.players });\n },\n};\n```\n\n```js\nconnection.onMessage((msg) => {\n if (msg.t !== 'snap') return;\n match.setNumber(msg.n); // a new match number means: reset, the round moved on\n for (const [id, p] of Object.entries(msg.players)) {\n if (id === connection.playerId) {\n // My own entry: the server owns all of it except where I am right now.\n Object.assign(me, { hp: p.hp, kills: p.kills, alive: p.alive });\n if (Math.hypot(p.x - me.x, p.y - me.y) > SNAP_DISTANCE) {\n me.x = p.x; // drifted too far to argue; the server is right\n me.y = p.y;\n }\n continue;\n }\n remote.set(id, { ...p, seenAt: performance.now() });\n }\n});\n```\n\nDo not build a per-player payload (\"everyone except you\") on the server: the\nclient needs its own entry anyway, and one tailored message per player costs N\nframes where the shared snapshot costs 1.\n\n## One-off events must be self-healing\n\nA dropped or missed event frame is gone for good. So an event may carry an\neffect, never the only copy of a result:\n\n- `{ t: 'hit', target, dmg }` -- fine for a flash, a sound, a particle.\n- The hp it produced, whether the player is alive or wrecked, the kill count,\n the match number: all of that belongs in the periodic snapshot, and the\n client reconciles from the snapshot every tick.\n\nWrite the client so that receiving zero events and only snapshots still\nproduces a correct, playable screen. Then a dropped frame costs one missing\nspark instead of a player who is dead everywhere but on their own device.\n\n## Connection loss has to be visible\n\nTwo independent things can go quiet: the socket, and a player.\n\n```js\nconnection.onStateChange((state, meta) => {\n // 'acquiring' | 'connecting' | 'connected' | 'reconnecting' | 'closed'\n // meta?.type: 'connectionLost' | 'replaced' | 'bye' | 'left' | 'error'\n hud.setConnection(state, meta?.type);\n});\n```\n\n- Show `reconnecting` and `closed` in the deck's own UI. A player staring at a\n frozen game with no explanation assumes the game is broken.\n- On `closed` with `replaced`, call `Multiplayer.join` again: the creator\n published a new server. A `public` join from matchmaking lands on the new\n version; a `named` or `party` room, or a friend's public room the player\n followed, keeps the old one until Castle ends it, about ten minutes after the\n save. That ending, like a kick, arrives as `bye` with a `reason` to show\n the player; don't rejoin a `bye` automatically, or a kicked player comes\n straight back.\n- Expire a remote player whose last snapshot is older than a few seconds\n (`performance.now() - p.seenAt > 3000`) and stop drawing them. This must run\n off the client's own clock, not off an event -- if the server or the socket\n goes silent, no message will ever arrive to tell you, and every remote player\n stays frozen mid-stride forever.\n- The SDK reconnects short drops by itself and `send` is safe to call while the\n socket is down (those messages are dropped), so the client's job is to show\n the state and recover, not to manage the socket.\n\n## Reconnects: park match state, never delete it\n\n`playerId` is stable across a platform reconnect, but the server still sees\n`onPlayerLeave` and then `onPlayerJoin`. A server that deletes the player's row\non leave silently drops a reconnecting player out of the match while their\nclient happily thinks it is still playing.\n\n```js\nonPlayerLeave(session, player) {\n const parked = state.players[player.playerId];\n delete state.players[player.playerId];\n if (parked) state.parked.set(player.playerId, { at: Date.now(), parked }); // or by userId\n},\nonPlayerJoin(session, player) {\n const held = state.parked.get(player.playerId);\n state.parked.delete(player.playerId);\n state.players[player.playerId] =\n held && Date.now() - held.at < 60_000 ? held.parked : freshPlayer();\n session.send(player.playerId, { t: 'full', ...fullState() }); // 1 frame, once\n},\n```\n\nPark for about 60 seconds (the platform's own reconnect window), keyed by\n`playerId`, or by `userId` when the match should survive a genuinely new\nconnection from the same account. Sweep expired entries on a tick.\n\nOn the client, after a state change back to `connected`, ask for full state\nonce and rebuild from the answer rather than assuming the world is as you left\nit.\n\n## The server ignores and tells\n\nWhen the server refuses a message because the player is not in the state the\nclient assumed -- not in the match, already dead, not their turn -- do not just\n`return`. The client believes something false and nothing will correct it.\n\n```js\nonMessage(session, player, data) {\n const me = state.players[player.playerId];\n if (!me || !me.alive) {\n session.send(player.playerId, { t: 'full', ...fullState() }); // authoritative answer\n return;\n }\n ...\n}\n```\n\nOne frame, and the client resyncs instead of arguing with itself. Rate-limit\nthat reply (once per player per second is plenty) so a looping client cannot\nspend the whole budget on corrections.\n\n## Client to server\n\nClient frames are capped at 16 KB and about 30 messages per second; **exceeding\nthe rate closes the socket**, which is much harsher than the server side's\nsilent drop.\n\n- Throttle pose/input sends to a fixed rate. 8-15 per second is plenty when the\n client interpolates between samples (the real-time kit reports at 20). Never\n send once per animation frame -- 60/s closes the connection.\n- Send intent (\"I am holding left\", \"I fired\"), not results. The server decides\n what happened.\n- Coalesce: one message per send tick carrying the latest pose beats three\n messages describing how it got there.\n\n## Testing it\n\n- Open **four or more** tabs, not two. Every budget and roster bug scales with\n the player count, and two tabs is exactly the case that never reproduces one.\n- Reload tabs mid-match to exercise leave/rejoin, and leave one tab idle to see\n what a silent player looks like to everyone else.\n- Kill and restart the serve (or edit the server entry, which restarts it) to\n see the disconnected state the deck shows.\n- Watch the serve log for the `[multiplayer]` budget warning and for dropped\n oversize frames while you play.\n- A published room that crashed or stopped: `castle-web logs` prints its end\n reason, exit code and last server log lines (creator only; `--rooms` lists rooms).\n";
1
+ export declare const MULTIPLAYER_DOC = "# Multiplayer, in practice\n\nRead this before writing or changing a server entry or client netcode by hand.\nWritten fresh by the Castle CLI at every serve start; the full API reference is\nthe SDK's own, at `imports/castle.base/sdk/README.md`.\n\n## Reach for a kit first\n\n`castle.multiplayer-2d` and `castle.multiplayer-3d` (both on `castle.real-time`)\nalready do everything below: a server-authoritative world, one snapshot per\ntick, pose interpolation, roster handling, reconnects, ownership of loose\nobjects. `castle.turn-based` does the same for games played in turns, with\nseats, spectators and idle clearing. A deck on one of those kits normally\nwrites nothing against the raw session API, and the right move is usually to\nadd a rule to the deck's own game hooks rather than a message of your own.\n\nHand-roll only when the game genuinely does not fit them -- and then keep the\nshape below, because it is the shape the platform's limits ask for.\n\n## The outbound budget\n\nA session may send about `40 + 40 x connected players` frames per second, with\nroughly two seconds of burst, and about 1 MiB/s of bytes. What a frame costs:\n\n| call | frames |\n|---|---|\n| `session.send(playerId, data)` | 1 |\n| `session.broadcast(data)` | 1, whatever the player count |\n| `session.broadcast(data, { except })` | one per recipient -- it is a loop of sends |\n\nFrames over the budget are **dropped silently**. The session keeps running and\na dropped frame is never retried, so the symptom is not an error: it is a\nclient whose world quietly stops matching everyone else's. Only sustained abuse\nat several times the budget ends a session.\n\nThe arithmetic that matters, at `tickRate: 20`:\n\n- 4 players, one `send` per player per tick: 80 frames/s of a 200 budget --\n before a single hit, join, chat or one-off frame.\n- 8 players, same: 160 of 360. A second per-player message per tick makes it\n 320, and at `tickRate: 30` that is 480 -- over, and frames start dropping.\n- Either, with one `broadcast` per tick: 20 frames/s. The budget stops being\n something you have to think about.\n\nPer-player sends also send the same bytes N times toward the byte budget. The\nlocal serve does not drop anything, but it warns when a 1-second window goes\nover -- `[multiplayer] server sent ...` in `.castle/logs.txt` and in the serve's\nown output (`.castle/serve.log` when it was detached).\n\n## The snapshot pattern\n\nAuthoritative state lives on the server. `onTick` builds ONE snapshot of every\nplayer and broadcasts it once.\n\nEvery client reads EVERY entry in that snapshot, **including its own** -- the\ndifference is only what it does with each:\n\n- **Other players' entries** drive what it draws for them (interpolated between\n snapshots), and are how it learns someone left or went silent.\n- **Its own entry** is the server's verdict on itself. Take hp, alive/wrecked,\n kills, score and the match state from it every tick, exactly as if it were\n someone else's. The one field it does NOT overwrite each tick is its own pose:\n the local player moves on its own input so the game stays responsive, and the\n client only snaps to the server's position when the two have drifted far\n apart. Ignoring the rest of its own entry is how a player ends up alive on\n their own screen and dead on everyone else's.\n\n```js\nconst state = { matchNumber: 1, players: {}, parked: new Map() };\n\nexport default {\n onPlayerJoin(session, player) {\n state.players[player.playerId] = { x: 0, y: 0, hp: 100, kills: 0, alive: true };\n },\n onMessage(session, player, data) {\n if (data.t === 'move') applyMove(state.players[player.playerId], data);\n },\n onTick(session) {\n // One frame per tick, for any number of players.\n session.broadcast({ t: 'snap', n: state.matchNumber, players: state.players });\n },\n};\n```\n\n```js\nconnection.onMessage((msg) => {\n if (msg.t !== 'snap') return;\n match.setNumber(msg.n); // a new match number means: reset, the round moved on\n for (const [id, p] of Object.entries(msg.players)) {\n if (id === connection.playerId) {\n // My own entry: the server owns all of it except where I am right now.\n Object.assign(me, { hp: p.hp, kills: p.kills, alive: p.alive });\n if (Math.hypot(p.x - me.x, p.y - me.y) > SNAP_DISTANCE) {\n me.x = p.x; // drifted too far to argue; the server is right\n me.y = p.y;\n }\n continue;\n }\n remote.set(id, { ...p, seenAt: performance.now() });\n }\n});\n```\n\nDo not build a per-player payload (\"everyone except you\") on the server: the\nclient needs its own entry anyway, and one tailored message per player costs N\nframes where the shared snapshot costs 1.\n\n## One-off events must be self-healing\n\nA dropped or missed event frame is gone for good. So an event may carry an\neffect, never the only copy of a result:\n\n- `{ t: 'hit', target, dmg }` -- fine for a flash, a sound, a particle.\n- The hp it produced, whether the player is alive or wrecked, the kill count,\n the match number: all of that belongs in the periodic snapshot, and the\n client reconciles from the snapshot every tick.\n\nWrite the client so that receiving zero events and only snapshots still\nproduces a correct, playable screen. Then a dropped frame costs one missing\nspark instead of a player who is dead everywhere but on their own device.\n\n## Connection loss has to be visible\n\nTwo independent things can go quiet: the socket, and a player.\n\n```js\nconnection.onStateChange((state, meta) => {\n // 'acquiring' | 'connecting' | 'connected' | 'reconnecting' | 'closed'\n // meta?.type: 'connectionLost' | 'replaced' | 'bye' | 'left' | 'error'\n hud.setConnection(state, meta?.type);\n});\n```\n\n- Show `reconnecting` and `closed` in the deck's own UI. A player staring at a\n frozen game with no explanation assumes the game is broken.\n- On `closed` with `replaced`, call `Multiplayer.join` again: the creator\n published a new server. A `public` join from matchmaking lands on the new\n version; a `named` or `party` room, or a friend's public room the player\n followed, keeps the old one until Castle ends it, about ten minutes after the\n save. That ending, like a kick, arrives as `bye` with a `reason` to show\n the player; don't rejoin a `bye` automatically, or a kicked player comes\n straight back.\n- Expire a remote player whose last snapshot is older than a few seconds\n (`performance.now() - p.seenAt > 3000`) and stop drawing them. This must run\n off the client's own clock, not off an event -- if the server or the socket\n goes silent, no message will ever arrive to tell you, and every remote player\n stays frozen mid-stride forever.\n- The SDK reconnects short drops by itself and `send` is safe to call while the\n socket is down (those messages are dropped), so the client's job is to show\n the state and recover, not to manage the socket.\n\n## Reconnects: park match state, never delete it\n\n`playerId` is stable across a platform reconnect, but the server still sees\n`onPlayerLeave` and then `onPlayerJoin`. A server that deletes the player's row\non leave silently drops a reconnecting player out of the match while their\nclient happily thinks it is still playing.\n\n```js\nonPlayerLeave(session, player) {\n const parked = state.players[player.playerId];\n delete state.players[player.playerId];\n if (parked) state.parked.set(player.playerId, { at: Date.now(), parked }); // or by userId\n},\nonPlayerJoin(session, player) {\n const held = state.parked.get(player.playerId);\n state.parked.delete(player.playerId);\n state.players[player.playerId] =\n held && Date.now() - held.at < 60_000 ? held.parked : freshPlayer();\n session.send(player.playerId, { t: 'full', ...fullState() }); // 1 frame, once\n},\n```\n\nPark for about 60 seconds (the platform's own reconnect window), keyed by\n`playerId`, or by `userId` when the match should survive a genuinely new\nconnection from the same account. Sweep expired entries on a tick.\n\nOn the client, after a state change back to `connected`, ask for full state\nonce and rebuild from the answer rather than assuming the world is as you left\nit.\n\n## The server ignores and tells\n\nWhen the server refuses a message because the player is not in the state the\nclient assumed -- not in the match, already dead, not their turn -- do not just\n`return`. The client believes something false and nothing will correct it.\n\n```js\nonMessage(session, player, data) {\n const me = state.players[player.playerId];\n if (!me || !me.alive) {\n session.send(player.playerId, { t: 'full', ...fullState() }); // authoritative answer\n return;\n }\n ...\n}\n```\n\nOne frame, and the client resyncs instead of arguing with itself. Rate-limit\nthat reply (once per player per second is plenty) so a looping client cannot\nspend the whole budget on corrections.\n\n## Client to server\n\nClient frames are capped at 16 KB and about 30 messages per second; **exceeding\nthe rate closes the socket**, which is much harsher than the server side's\nsilent drop.\n\n- Throttle pose/input sends to a fixed rate. 8-15 per second is plenty when the\n client interpolates between samples (the real-time kit reports at 20). Never\n send once per animation frame -- 60/s closes the connection.\n- Send intent (\"I am holding left\", \"I fired\"), not results. The server decides\n what happened.\n- Coalesce: one message per send tick carrying the latest pose beats three\n messages describing how it got there.\n\n## Testing it\n\n- Open **four or more** tabs, not two. Every budget and roster bug scales with\n the player count, and two tabs is exactly the case that never reproduces one.\n- Reload tabs mid-match to exercise leave/rejoin, and leave one tab idle to see\n what a silent player looks like to everyone else.\n- Kill and restart the serve (or edit the server entry, which restarts it) to\n see the disconnected state the deck shows.\n- Watch the serve log for the `[multiplayer]` budget warning and for dropped\n oversize frames while you play.\n- A published room that crashed or stopped: `castle-web logs` prints its end\n reason, exit code and last server log lines (creator only; `--rooms` lists rooms).\n The room list and the room view also show how many server messages were dropped\n for being over 64 KB.\n";
@@ -234,4 +234,6 @@ silent drop.
234
234
  oversize frames while you play.
235
235
  - A published room that crashed or stopped: \`castle-web logs\` prints its end
236
236
  reason, exit code and last server log lines (creator only; \`--rooms\` lists rooms).
237
+ The room list and the room view also show how many server messages were dropped
238
+ for being over 64 KB.
237
239
  `;
@@ -54,7 +54,7 @@ const MODE_BULLET = "- Unprompted, an editor is an offer, never a build: when th
54
54
  export function everyDeckBullets(deckDir) {
55
55
  return [
56
56
  "- **Castle's Parameters panel is where a creator tunes the deck.** It is one of Castle's own panels, beside Play and Files: it shows the `PARAMS` values of every file that has one as live fields the creator drags while the deck runs, which is how they change the way it plays without putting a cursor in code.",
57
- `- **Supported media formats are exactly**: ${mediaList(deckDir)}. Nothing else — a published deck inlines every asset as a \`data:\` URI, where the browser trusts the declared type instead of sniffing the bytes, so a format that merely works while serving (\`.mov\` is the classic case) can be dead once published. Convert, don't improvise.`,
57
+ `- **Supported media formats are exactly**: ${mediaList(deckDir)}. Nothing else — a published deck inlines every asset as a \`data:\` URI, where the browser trusts the declared type instead of sniffing the bytes, so a format that merely works while serving (\`.mov\` is the classic case) can be dead once published. Convert, don't improvise. Audio and video (\`.mp4\`, \`.webm\`) of 64 KB or more are the assets not inlined: a published deck serves them from Castle's CDN by URL, so play them with \`new Audio(url)\`, \`video.src = url\` or \`fetch\` + \`decodeAudioData\`, never by reading the string (an \`?inline\` import keeps the \`data:\` URI).`,
58
58
  "- To add an npm package, put it in `package.json` `dependencies` and run `castle-web install .` (the install `init` ran; it uses whichever package manager made the lockfile).",
59
59
  "- Do not reload the deck after an edit. Nothing auto-reloads: the person applies your changes when they are ready, from the Play panel's restart button or a panel's own reload control. `npm run restart` reloads every open panel at once and breaks their flow — only when asked.",
60
60
  '- If the browser console shows `[vite] failed to connect to websocket` (or a "Direct websocket connection fallback" line), ignore it. Vite HMR is deliberately off on this serve, so the line is expected and harmless: it is never why a scene is blank, a game is not running, or multiplayer is not connecting. Do not investigate or "fix" it.',
@@ -80,6 +80,7 @@ export const HOST_LIMIT_BULLETS = [
80
80
  "- **Where a deck runs decides what it can do.** The Play panel runs it from this serve; players run the published deck in the Castle app (iOS, Android) or castle.xyz's web player. When something works in one and fails in another, check it against the limits below before another fix: if one covers it, name that limit instead of retrying, and ask where they run it if you do not know. If none does, it is an ordinary deck bug (a runtime `fetch` of a loose file, a control that only answers a mouse) and gets fixed.",
81
81
  "- **Microphone and camera are blocked in the Play panel and on castle.xyz**: neither frame is granted them, so `getUserMedia` rejects with `NotAllowedError` whatever the person allows, and no deck change helps. The Android app's published deck can use them; the iOS app is untested.",
82
82
  "- **A published deck loads almost nothing from the network.** Its CSP allows images, audio and video only from the deck itself, `data:` or `blob:`, `fetch` only to esm.sh, cdnjs.cloudflare.com and Castle's multiplayer hosts, and no iframes. The Play panel enforces the same CSP, so a URL it blocks fails in Play too, and `.castle/logs.txt` names each URL and directive the page blocked with a `[csp] blocked` line. Bundle the file, or let the player pick one with `<input type=\"file\">`.",
83
+ "- **On castle.xyz a published deck's frame has no origin of its own, and on a device its console reaches no devtools.** Browser storage throws a `SecurityError` there, and so do history calls that pass a URL. Don't build on browser storage; the SDK's replacements, how `setup()` keeps history calls working, and the on-screen console for debugging on a device are in the SDK reference, `imports/castle.base/sdk/README.md`.",
83
84
  "- **An older Castle app build rejects SDK commands newer than the build**, with a `CastleError` whose `code` is `UNKNOWN_COMMAND`; only an app update fixes that, so the deck should catch it and keep working. Which commands need which app build, and every other limit of a Castle service, is in the SDK reference, `imports/castle.base/sdk/README.md`.",
84
85
  ];
85
86
  // The frustration survey found the router inventing Upload buttons and offering
@@ -311,7 +312,7 @@ const COMMON_SECTIONS = `## Imports are read-only
311
312
  - **Limits worth designing around.** Client→server messages are capped at 16 KB and about 30 per second; server→client messages are capped at 64 KB. These limits apply to both JSON and binary frames and are measured on the frame, so a binary frame's one-byte protocol tag leaves you one byte under the cap for payload. A session may also SEND only about \`40 + 40 × connected players\` frames per second (about two seconds of burst, and about 1 MiB/s of bytes): \`session.send\` costs one frame per call, \`session.broadcast(data)\` costs ONE frame however many players are in the session, and \`session.broadcast(data, { except })\` is a loop of sends, so it costs one frame per recipient. Frames over the budget are dropped silently and never retried — the session keeps running, so the symptom is a client whose world quietly stops matching everyone else's; only sustained abuse at several times the budget ends a session. So send one \`broadcast\` per tick carrying every player's state, rather than a tailored \`send\` per player: every client reads every entry of that snapshot INCLUDING its own — it takes hp, kills and match state from its own entry and only keeps its own position locally predicted.
312
313
  - **Binary messages are opt-in per payload.** Pass any typed array, \`DataView\`, or \`ArrayBuffer\` to client \`send\`, server \`send\`, or server \`broadcast\` to send its raw bytes. \`onMessage\` always receives those bytes as a \`Uint8Array\`, while every other payload continues to use JSON. Reconstruct another view type such as \`Float32Array\` on receipt; multi-byte values use the sender platform's byte order.
313
314
  - **Test multiplayer locally with no setup.** \`castle-web serve\` runs your server file alongside the deck. Open the shell URL it prints in two tabs, then open the Play panel in each; those play surfaces share a session. If you open the content origin from \`.castle/serve.json\` directly, use \`/index.html?edit=0\`. Its bare origin loads the edit surface, where \`Multiplayer.join\` is not answered. Editing the server entry, anything beside it, or a deck-owned hook under \`server/\` or \`code/server/\` restarts it and clients reconnect, so you exercise your reconnect path constantly. Server \`console.log\` goes to the serve's logs, not the browser console.
314
- - **A published deck's server rooms have logs too.** \`castle-web logs\` (in the deck folder, signed in as its creator) shows the newest room's state, end reason, exit code, an out-of-memory kill, and its last server log lines; \`--rooms\` lists recent rooms and \`--room <id>\` picks one. Hosts keep the lines for about 30 minutes after a room ends.
315
+ - **A published deck's server rooms have logs too.** \`castle-web logs\` (in the deck folder, signed in as its creator) shows the newest room's state, end reason, exit code, an out-of-memory kill, and its last server log lines; \`--rooms\` lists recent rooms and \`--room <id>\` picks one. Hosts keep the lines for about 30 minutes after a room ends. The room list and the room view also show how many server messages were dropped for being over 64 KB.
315
316
  - **Publishing moves players onto the new version; you don't build versioned rooms or a rejoin prompt.** \`save-deck\` bundles and publishes the server entry, and every new session runs it. A session already running keeps the code it started with: its server gets \`onReplaced\`, and each client's connection closes with \`replaced\` metadata. A deck that joins again when the connection closes (the multiplayer kits do) gets the new version at once for a \`public\` join from matchmaking, since new players are not placed in a running public session on the old code; a \`named\` or \`party\` join, or a public one that follows a friend into their room, goes back to that room, which keeps the old code until it ends. About ten minutes after the save Castle ends any ordinary session still on the old code (hub places, persistent worlds and destinations keep their own release handling), closing its connections with \`bye\` and a reason that says the game was updated; its \`onShutdown\` still runs, so a save there lands, and the next join gets the new version.
316
317
  `;
317
318
  export function platformGuide(deckDir) {
@@ -12,13 +12,17 @@ const CONTENT_PACK_HOSTS = 'https://hosted.castle.games';
12
12
  // `Access-Control-Allow-Origin: *`, so a fetch from the opaque srcdoc origin can read
13
13
  // them. img-src, media-src and connect-src only: an asset is data, never script.
14
14
  export const CASTLE_ASSET_HOSTS = 'https://castle.imgix.net https://image.castle.xyz https://audio.castle.xyz';
15
+ // A published deck's audio and video, which save-deck stores there instead of
16
+ // inlining it (bundle.ts ExternalMedia). Path-scoped and media-src only: a fetch
17
+ // for decodeAudioData is already covered by CONTENT_PACK_HOSTS in connect-src.
18
+ const MEDIA_ASSET_SRC = 'https://hosted.castle.games/cauldron-assets/';
15
19
  const DECK_CSP = [
16
20
  "default-src 'self' data: blob:",
17
21
  `script-src 'self' 'unsafe-inline' 'unsafe-eval' 'wasm-unsafe-eval' data: blob: ${CDN_HOSTS}`,
18
22
  "style-src 'self' 'unsafe-inline' data: blob: https://fonts.googleapis.com",
19
23
  "font-src 'self' data: blob: https://fonts.gstatic.com",
20
24
  `img-src 'self' data: blob: ${CASTLE_ASSET_HOSTS}`,
21
- `media-src 'self' data: blob: ${CASTLE_ASSET_HOSTS}`,
25
+ `media-src 'self' data: blob: ${CASTLE_ASSET_HOSTS} ${MEDIA_ASSET_SRC}`,
22
26
  `connect-src 'self' data: blob: ${CDN_HOSTS} ${PLAY_HOSTS} ${CONTENT_PACK_HOSTS} ${CASTLE_ASSET_HOSTS}`,
23
27
  "frame-src 'none'",
24
28
  "child-src 'self' blob:",
@@ -1,11 +1,18 @@
1
1
  export interface ResetLeaderboardsOptions {
2
2
  deckId?: string;
3
3
  yes: boolean;
4
+ undo?: boolean;
4
5
  }
6
+ export declare const NOT_WEB_DECK = "DECK_DATA_RESET_NOT_WEB_DECK";
7
+ export declare function needsClassicClear(err: unknown): boolean;
5
8
  export interface ResetLeaderboardsDeps {
6
9
  signedIn: boolean;
7
10
  deckTitle(deckId: string): Promise<string | null>;
8
- clearDeckLeaderboards(deckId: string): Promise<void>;
11
+ resetDeckLeaderboards(deckId: string): Promise<{
12
+ undoUntil: string | null;
13
+ }>;
14
+ undoDeckLeaderboardsReset(deckId: string): Promise<void>;
15
+ clearClassicLeaderboards(deckId: string): Promise<void>;
9
16
  interactive: boolean;
10
17
  confirm(question: string): Promise<boolean>;
11
18
  log(line: string): void;
@@ -1,11 +1,25 @@
1
1
  // `castle-web reset-leaderboards` -- clears every leaderboard on a deck, for its
2
- // creator. Ghost's clearDeckLeaderboards starts each variable and scope on the
3
- // deck over from empty; the old scores are never shown again, and there is no
4
- // undo. The classic editor's "Reset all leaderboards" button sends the same
5
- // mutation.
2
+ // creator. For a Cauldron deck it sends Ghost's resetCauldronDeckLeaderboards, which
3
+ // starts the Store boards and the classic leaderboards over from empty and can be
4
+ // undone for a day with `--undo`; the players' saved data is untouched. A classic
5
+ // deck (Ghost refuses it with DECK_DATA_RESET_NOT_WEB_DECK) falls back to
6
+ // clearDeckLeaderboards, the classic editor's "Reset all leaderboards", which has no
7
+ // undo.
6
8
  //
7
- // This command is for a signed-in creator at a terminal. The mutation is left
8
- // out of the cloud sandbox's GraphQL allowlist, so the deck agent cannot send it.
9
+ // This command is for a signed-in creator at a terminal. Neither mutation is in the
10
+ // cloud sandbox's GraphQL allowlist, so the deck agent cannot send them.
11
+ // Ghost's refusal of a classic deck, from the Cauldron reset.
12
+ export const NOT_WEB_DECK = 'DECK_DATA_RESET_NOT_WEB_DECK';
13
+ // Whether the Cauldron reset cannot run here and the classic clear should: a classic
14
+ // deck, or a Ghost from before resetCauldronDeckLeaderboards existed (so this CLI can
15
+ // publish ahead of the server). The classic clear has no undo and leaves Store boards.
16
+ export function needsClassicClear(err) {
17
+ const failure = err;
18
+ if (failure?.extensions?.code === NOT_WEB_DECK)
19
+ return true;
20
+ // Ghost's GraphQL Yoga reports an unknown field with this message and no code.
21
+ return String(failure?.message).includes('Cannot query field "resetCauldronDeckLeaderboards"');
22
+ }
9
23
  export async function resetLeaderboards(options, deps) {
10
24
  const deckId = options.deckId;
11
25
  if (!deckId) {
@@ -18,18 +32,39 @@ export async function resetLeaderboards(options, deps) {
18
32
  // still decides whether the deck exists and is this user's.
19
33
  const title = await deps.deckTitle(deckId);
20
34
  const named = title ? `"${title}" (${deckId})` : `deck ${deckId}`;
35
+ if (options.undo) {
36
+ await deps.undoDeckLeaderboardsReset(deckId);
37
+ deps.log(`Put back the leaderboards of ${named} as they were before the last reset.`);
38
+ return;
39
+ }
21
40
  if (!options.yes) {
22
41
  if (!deps.interactive) {
23
42
  throw new Error(`Not resetting the leaderboards of ${named}: there is no terminal to confirm on. Pass --yes to reset anyway.`);
24
43
  }
25
- const question = `Reset every leaderboard on ${named}? All of its scores are cleared, and this cannot be undone. [y/N] `;
44
+ const question = `Reset every leaderboard on ${named}? All of its scores are cleared; players' saved data is kept. [y/N] `;
26
45
  if (!(await deps.confirm(question))) {
27
46
  deps.log('Nothing was reset.');
28
47
  return;
29
48
  }
30
49
  }
31
- await deps.clearDeckLeaderboards(deckId);
50
+ let undoUntil;
51
+ try {
52
+ ({ undoUntil } = await deps.resetDeckLeaderboards(deckId));
53
+ }
54
+ catch (err) {
55
+ if (!needsClassicClear(err)) {
56
+ throw err;
57
+ }
58
+ await deps.clearClassicLeaderboards(deckId);
59
+ deps.log(`Reset the classic leaderboards on ${named} for good: there is no undo here.`);
60
+ return;
61
+ }
32
62
  deps.log(`Reset every leaderboard on ${named}. They start empty from the next score.`);
63
+ if (undoUntil) {
64
+ // Names the deck: --undo skips the prompt, and run from another deck's directory
65
+ // the bare command would undo that deck instead.
66
+ deps.log(`Changed your mind? \`castle-web reset-leaderboards --deck-id ${deckId} --undo\` puts the scores back until ${undoUntil}.`);
67
+ }
33
68
  }
34
69
  // The answer to the confirmation question: only a y or yes resets.
35
70
  export function isYes(answer) {
@@ -5,6 +5,7 @@ export interface CauldronRoom {
5
5
  startedAt: string;
6
6
  endedAt: string | null;
7
7
  numPlayers: number;
8
+ oversizeDrops: number | null;
8
9
  }
9
10
  export interface CauldronRoomLogLine {
10
11
  at: string | null;
package/dist/roomLogs.js CHANGED
@@ -13,6 +13,9 @@ import { readCastleJson } from './castleJson.js';
13
13
  import * as config from './config.js';
14
14
  const RECENT_ROOMS_LIMIT = 20;
15
15
  const ROOM_FIELDS = 'sessionId deckId env startedAt endedAt numPlayers';
16
+ // Selected separately: a Ghost older than the field rejects the whole document, so the
17
+ // query is retried once without it (see query below).
18
+ const OVERSIZE_FIELD = 'oversizeDrops';
16
19
  const UNAVAILABLE_REASONS = {
17
20
  host_missing: 'the server host that ran this room is gone (hosts are replaced over time), so its logs went with it',
18
21
  host_stale: 'the server host that ran this room has stopped reporting in, so its logs cannot be read',
@@ -31,8 +34,16 @@ const ERROR_CODES = {
31
34
  };
32
35
  export class RoomLogsError extends Error {
33
36
  }
37
+ // `document` builds the query with or without oversizeDrops. A Ghost that predates the
38
+ // field fails validation naming it; then the query runs once more without it and every
39
+ // room's count is unknown (null).
34
40
  async function query(document, variables, field) {
35
- const response = await graphql(document, variables);
41
+ let response = await graphql(document(OVERSIZE_FIELD), variables);
42
+ let withOversize = true;
43
+ if (response.errors?.some((e) => /Cannot query field "oversizeDrops"/.test(e.message ?? ''))) {
44
+ response = await graphql(document(''), variables);
45
+ withOversize = false;
46
+ }
36
47
  const error = response.errors?.[0];
37
48
  if (error)
38
49
  throw new RoomLogsError(describeError(error));
@@ -40,6 +51,10 @@ async function query(document, variables, field) {
40
51
  if (value === undefined || value === null) {
41
52
  throw new RoomLogsError(`The server returned no ${field}.`);
42
53
  }
54
+ if (!withOversize) {
55
+ for (const room of Array.isArray(value) ? value : [value])
56
+ room.oversizeDrops = null;
57
+ }
43
58
  return value;
44
59
  }
45
60
  function describeError(error) {
@@ -54,16 +69,16 @@ function describeError(error) {
54
69
  return visible(code ? `${message} [${code}]` : message);
55
70
  }
56
71
  export function recentRooms(deckId, env, limit = RECENT_ROOMS_LIMIT) {
57
- return query(`query($deckId: ID!, $env: String, $limit: Int) {
72
+ return query((oversize) => `query($deckId: ID!, $env: String, $limit: Int) {
58
73
  cauldronRecentRooms(deckId: $deckId, env: $env, limit: $limit) {
59
- ${ROOM_FIELDS}
74
+ ${ROOM_FIELDS} ${oversize}
60
75
  }
61
76
  }`, { deckId, env, limit }, 'cauldronRecentRooms');
62
77
  }
63
78
  export function roomLogs(deckId, sessionId, env) {
64
- return query(`query($deckId: ID!, $sessionId: ID!, $env: String) {
79
+ return query((oversize) => `query($deckId: ID!, $sessionId: ID!, $env: String) {
65
80
  cauldronRoomLogs(deckId: $deckId, sessionId: $sessionId, env: $env) {
66
- ${ROOM_FIELDS}
81
+ ${ROOM_FIELDS} ${oversize}
67
82
  state logsAvailable logsUnavailableReason endReason exitCode oomKilled droppedLines
68
83
  lines { at stream text }
69
84
  }
@@ -98,12 +113,16 @@ export function formatRooms(deckId, env, rooms) {
98
113
  shortTime(room.startedAt),
99
114
  room.endedAt ? shortTime(room.endedAt) : 'running',
100
115
  String(room.numPlayers),
116
+ hasOversizeDrops(room) ? `${room.oversizeDrops} message${room.oversizeDrops === 1 ? '' : 's'} dropped (over 64 KB)` : '',
101
117
  ].map((cell) => visible(String(cell))));
102
- const header = ['ROOM', 'STARTED', 'ENDED', 'PLAYERS'];
118
+ const header = ['ROOM', 'STARTED', 'ENDED', 'PLAYERS', ''];
103
119
  const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
104
120
  const line = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join(' ').trimEnd();
105
121
  return [`Recent rooms of deck ${deckId} (${env}), newest first:`, line(header), ...rows.map(line)].join('\n');
106
122
  }
123
+ function hasOversizeDrops(room) {
124
+ return typeof room.oversizeDrops === 'number' && room.oversizeDrops > 0;
125
+ }
107
126
  export function formatRoomLogs(logs) {
108
127
  const out = [
109
128
  `Room ${logs.sessionId} of deck ${logs.deckId} (${logs.env})`,
@@ -118,6 +137,11 @@ export function formatRoomLogs(logs) {
118
137
  out.push(` exit code: ${logs.exitCode}`);
119
138
  if (logs.oomKilled)
120
139
  out.push(' killed: out of memory');
140
+ if (hasOversizeDrops(logs)) {
141
+ const n = logs.oversizeDrops;
142
+ out.push(` ${n} server message${n === 1 ? ' was' : 's were'} dropped for being over 64 KB. ` +
143
+ 'Send smaller messages: split the state, or send only what changed.');
144
+ }
121
145
  if (!logs.logsAvailable) {
122
146
  const reason = logs.logsUnavailableReason ?? '';
123
147
  out.push('', `No log lines: ${UNAVAILABLE_REASONS[reason] ?? `unavailable (${reason || 'no reason given'})`}.`);
@@ -1,12 +1,13 @@
1
1
  import * as api from './api.js';
2
- import { type BundleChunk } from './bundle.js';
2
+ import { type BundleChunk, type ExternalMediaAsset } from './bundle.js';
3
3
  import { type ExperimentConfig } from './castleJson.js';
4
4
  import { type SavePrecondition } from './webSourceSync.js';
5
5
  export { DeckTooLargeError, MAX_SCENE_DATA_BYTES, MAX_SOURCE_ARCHIVE_BYTES, sceneTooLargeMessage, sourceTooLargeMessage, } from './saveFailure.js';
6
6
  export declare const SOURCE_ARCHIVE_EXCLUDES: string[];
7
7
  export declare const SAVE_STAGE_TELEMETRY_PREFIX = "CASTLE_SAVE_TELEMETRY ";
8
8
  export declare const SAVE_COVER_SELECTION_TELEMETRY_PREFIX = "CASTLE_SAVE_COVER_SELECTION ";
9
- export type SaveStage = 'bundle' | 'cover' | 'chunk_upload' | 'scene_upload_config' | 'scene_upload' | 'content_publish' | 'server_publish' | 'source_archive' | 'source_upload_config' | 'source_upload' | 'source_commit';
9
+ export declare const SAVE_ASSET_INLINE_TELEMETRY_PREFIX = "CASTLE_SAVE_ASSET_INLINE ";
10
+ export type SaveStage = 'bundle' | 'cover' | 'chunk_upload' | 'asset_upload' | 'scene_upload_config' | 'scene_upload' | 'content_publish' | 'server_publish' | 'source_archive' | 'source_upload_config' | 'source_upload' | 'source_commit';
10
11
  export declare function runTar(args: string[], opts?: {
11
12
  capture?: boolean;
12
13
  }): Promise<string>;
@@ -50,6 +51,35 @@ export declare function uploadBundleChunks(deckId: string, chunks: BundleChunk[]
50
51
  skipped: number;
51
52
  bytesUploaded: number;
52
53
  }>;
54
+ export declare const MAX_MEDIA_ASSET_BYTES: number;
55
+ export interface MediaUploadResult {
56
+ uploaded: number;
57
+ skipped: number;
58
+ bytesUploaded: number;
59
+ /** The URLs this upload stored (not the ones already there), to check are served. */
60
+ storedUrls: string[];
61
+ /** Assets Ghost refused, with its code: the page must be built with these inline. */
62
+ refused: {
63
+ asset: ExternalMediaAsset;
64
+ code: string;
65
+ }[];
66
+ }
67
+ export declare const ASSET_SERVED_RETRY_MS: number[];
68
+ /** True once every URL is served through the CDN, trying again after each wait. Exported for the tests. */
69
+ export declare function assetsServed(urls: string[], retryMs?: number[]): Promise<boolean>;
70
+ /**
71
+ * Puts every media asset the page names at its URL, as uploadBundleChunks does
72
+ * chunks: one already there (HEAD 200) is skipped, any other uploaded and
73
+ * stored, and the first that cannot be stored fails the save before the page
74
+ * is published -- except one Ghost refuses (ASSET_REFUSED), which is reported
75
+ * in `refused` for the caller to inline. Null when this Ghost has no asset
76
+ * store: the caller builds the page with its media inline instead.
77
+ * Exported for the tests.
78
+ */
79
+ export declare function uploadMediaAssets(deckId: string, assets: ExternalMediaAsset[], { busyRetryMs }?: {
80
+ busyRetryMs?: number[];
81
+ }): Promise<MediaUploadResult | null>;
82
+ export type AssetInlineReason = 'no_store' | 'cdn_not_serving' | 'refused';
53
83
  export type SaveVisibility = 'unlisted' | 'private';
54
84
  export interface SaveDeckOptions {
55
85
  title?: string;