castle-web-cli 0.4.238 → 0.4.240

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 (404) 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 +218 -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 +22 -3
  16. package/dist/init.js +24 -2
  17. package/dist/multiplayerDoc.d.ts +1 -1
  18. package/dist/multiplayerDoc.js +9 -0
  19. package/dist/platformDoc.js +4 -2
  20. package/dist/playPagePolicy.d.ts +1 -0
  21. package/dist/playPagePolicy.js +12 -3
  22. package/dist/resetLeaderboards.d.ts +8 -1
  23. package/dist/resetLeaderboards.js +43 -8
  24. package/dist/roomLogs.d.ts +39 -0
  25. package/dist/roomLogs.js +166 -0
  26. package/dist/save-deck.d.ts +32 -2
  27. package/dist/save-deck.js +240 -39
  28. package/kits/base/CLAUDE.md +2 -1
  29. package/kits/base/castle.json +1 -1
  30. package/kits/base/sdk/README.md +240 -8
  31. package/kits/base/sdk/analytics.d.ts +8 -0
  32. package/kits/base/sdk/analytics.js +92 -0
  33. package/kits/base/sdk/castle.d.ts +8 -2
  34. package/kits/base/sdk/castle.js +3 -0
  35. package/kits/base/sdk/commands.d.ts +79 -0
  36. package/kits/base/sdk/commands.js +1 -0
  37. package/kits/base/sdk/debugConsole.d.ts +17 -0
  38. package/kits/base/sdk/debugConsole.js +154 -0
  39. package/kits/base/sdk/experiments.js +24 -1
  40. package/kits/base/sdk/hostRetry.d.ts +7 -0
  41. package/kits/base/sdk/hostRetry.js +57 -0
  42. package/kits/base/sdk/hub.d.ts +20 -2
  43. package/kits/base/sdk/hub.js +99 -13
  44. package/kits/base/sdk/multiplayer.d.ts +2 -0
  45. package/kits/base/sdk/multiplayer.js +198 -26
  46. package/kits/base/sdk/reconnectBudget.d.ts +6 -0
  47. package/kits/base/sdk/reconnectBudget.js +41 -1
  48. package/kits/base/sdk/rooms.d.ts +11 -0
  49. package/kits/base/sdk/rooms.js +22 -0
  50. package/kits/base/sdk/runtime.js +36 -19
  51. package/kits/base/sdk/server/hub.d.ts +19 -0
  52. package/kits/base/sdk/server/hub.js +12 -0
  53. package/kits/base/sdk/server/platformHandle.d.ts +1 -0
  54. package/kits/base/sdk/server/wrapper.d.ts +1 -1
  55. package/kits/base/sdk/server/wrapper.js +26 -1
  56. package/kits/base/sdk/store.d.ts +8 -2
  57. package/kits/base/sdk/store.js +5 -1
  58. package/kits/base/sdk/transport.d.ts +2 -1
  59. package/kits/base/sdk/transport.js +35 -0
  60. package/kits/hub-game/CLAUDE.md +66 -19
  61. package/kits/hub-game/castle.json +4 -4
  62. package/kits/hub-game/code/client/act.js +9 -6
  63. package/kits/hub-game/code/client/actCore.js +26 -6
  64. package/kits/hub-game/code/client/actGateLog.js +36 -0
  65. package/kits/hub-game/code/client/actionOverflow.js +29 -8
  66. package/kits/hub-game/code/client/actionRailSurface.js +186 -0
  67. package/kits/hub-game/code/client/actionRailTree.js +173 -0
  68. package/kits/hub-game/code/client/askSurface.js +85 -0
  69. package/kits/hub-game/code/client/askTree.js +51 -0
  70. package/kits/hub-game/code/client/attention.js +31 -6
  71. package/kits/hub-game/code/client/ballot.js +42 -5
  72. package/kits/hub-game/code/client/ballotSurface.js +115 -0
  73. package/kits/hub-game/code/client/ballotTree.js +180 -0
  74. package/kits/hub-game/code/client/catchingUp.js +19 -0
  75. package/kits/hub-game/code/client/celebrate.js +66 -0
  76. package/kits/hub-game/code/client/chrome.js +474 -53
  77. package/kits/hub-game/code/client/companion.js +93 -23
  78. package/kits/hub-game/code/client/companionDress.js +1 -1
  79. package/kits/hub-game/code/client/cornerSurface.js +106 -0
  80. package/kits/hub-game/code/client/cornerTree.js +83 -0
  81. package/kits/hub-game/code/client/decor.js +20 -11
  82. package/kits/hub-game/code/client/deviceStorage.js +121 -0
  83. package/kits/hub-game/code/client/disguise.js +23 -0
  84. package/kits/hub-game/code/client/disguiseDraw.js +87 -0
  85. package/kits/hub-game/code/client/dockSurface.js +206 -0
  86. package/kits/hub-game/code/client/dockTree.js +232 -0
  87. package/kits/hub-game/code/client/earned.js +29 -0
  88. package/kits/hub-game/code/client/emoteSurface.js +188 -0
  89. package/kits/hub-game/code/client/emoteTree.js +264 -0
  90. package/kits/hub-game/code/client/farAvatars.js +4 -3
  91. package/kits/hub-game/code/client/fpsTelemetry.js +3 -1
  92. package/kits/hub-game/code/client/grab.js +121 -50
  93. package/kits/hub-game/code/client/holdShow.js +19 -0
  94. package/kits/hub-game/code/client/hookLayer.js +96 -12
  95. package/kits/hub-game/code/client/hubControls.js +7 -1
  96. package/kits/hub-game/code/client/hudSurface.js +11 -3
  97. package/kits/hub-game/code/client/hudTree.js +7 -4
  98. package/kits/hub-game/code/client/idle.js +21 -3
  99. package/kits/hub-game/code/client/invites.js +24 -3
  100. package/kits/hub-game/code/client/keys.js +15 -0
  101. package/kits/hub-game/code/client/labelsNear.js +8 -1
  102. package/kits/hub-game/code/client/layoutCache.js +57 -8
  103. package/kits/hub-game/code/client/loadingCover.js +53 -4
  104. package/kits/hub-game/code/client/menuIcons.js +15 -0
  105. package/kits/hub-game/code/client/menuRows.js +8 -2
  106. package/kits/hub-game/code/client/menuSurface.js +102 -0
  107. package/kits/hub-game/code/client/menuTree.js +135 -0
  108. package/kits/hub-game/code/client/modelLook.js +41 -0
  109. package/kits/hub-game/code/client/pickerSurface.js +152 -0
  110. package/kits/hub-game/code/client/pickerTree.js +163 -0
  111. package/kits/hub-game/code/client/pushVisit.js +4 -2
  112. package/kits/hub-game/code/client/quality.js +188 -29
  113. package/kits/hub-game/code/client/qualityEntry.js +10 -1
  114. package/kits/hub-game/code/client/quickChatSurface.js +222 -0
  115. package/kits/hub-game/code/client/quickChatTree.js +201 -0
  116. package/kits/hub-game/code/client/rehello.js +75 -0
  117. package/kits/hub-game/code/client/renderVisibility.js +17 -0
  118. package/kits/hub-game/code/client/replay.js +118 -0
  119. package/kits/hub-game/code/client/role.js +3 -0
  120. package/kits/hub-game/code/client/safeLayout.js +441 -56
  121. package/kits/hub-game/code/client/safeStyle.js +13 -10
  122. package/kits/hub-game/code/client/say.js +2 -0
  123. package/kits/hub-game/code/client/soundSurface.js +77 -0
  124. package/kits/hub-game/code/client/soundTree.js +74 -0
  125. package/kits/hub-game/code/client/soundscape.js +12 -9
  126. package/kits/hub-game/code/client/soundscapeCues.js +1 -1
  127. package/kits/hub-game/code/client/state.js +67 -1
  128. package/kits/hub-game/code/client/stuckSurface.js +76 -0
  129. package/kits/hub-game/code/client/stuckTree.js +67 -0
  130. package/kits/hub-game/code/client/talk.js +42 -12
  131. package/kits/hub-game/code/client/talkTree.js +4 -2
  132. package/kits/hub-game/code/client/textAskSurface.js +147 -0
  133. package/kits/hub-game/code/client/textAskTree.js +67 -0
  134. package/kits/hub-game/code/client/tiers.js +252 -27
  135. package/kits/hub-game/code/client/together.js +4 -1
  136. package/kits/hub-game/code/client/uiDom.js +86 -8
  137. package/kits/hub-game/code/client/uiTree.js +33 -4
  138. package/kits/hub-game/code/client/vehicle.js +75 -52
  139. package/kits/hub-game/code/client/weakestTier.js +75 -31
  140. package/kits/hub-game/code/client/wear.js +159 -5
  141. package/kits/hub-game/code/client/worldLabels.js +215 -26
  142. package/kits/hub-game/code/companionSpec.js +4 -2
  143. package/kits/hub-game/code/server/act.js +3 -0
  144. package/kits/hub-game/code/server/actGate.js +83 -0
  145. package/kits/hub-game/code/server/actions.js +71 -15
  146. package/kits/hub-game/code/server/actors.js +20 -5
  147. package/kits/hub-game/code/server/analytics.js +40 -15
  148. package/kits/hub-game/code/server/ask.js +39 -3
  149. package/kits/hub-game/code/server/ballot.js +167 -4
  150. package/kits/hub-game/code/server/celebrate.js +64 -0
  151. package/kits/hub-game/code/server/companion.js +17 -2
  152. package/kits/hub-game/code/server/decor.js +11 -2
  153. package/kits/hub-game/code/server/disguise.js +63 -0
  154. package/kits/hub-game/code/server/doorAnalytics.js +2 -5
  155. package/kits/hub-game/code/server/earned.js +6 -2
  156. package/kits/hub-game/code/server/friendBests.js +13 -4
  157. package/kits/hub-game/code/server/friendsAmong.js +67 -8
  158. package/kits/hub-game/code/server/grab.js +12 -2
  159. package/kits/hub-game/code/server/heldOffers.js +142 -0
  160. package/kits/hub-game/code/server/holdShow.js +98 -0
  161. package/kits/hub-game/code/server/hub.js +854 -45
  162. package/kits/hub-game/code/server/idle.js +110 -9
  163. package/kits/hub-game/code/server/index.js +9 -0
  164. package/kits/hub-game/code/server/labels.js +13 -3
  165. package/kits/hub-game/code/server/loadAbandon.js +2 -5
  166. package/kits/hub-game/code/server/manifest.js +94 -6
  167. package/kits/hub-game/code/server/menu.js +26 -3
  168. package/kits/hub-game/code/server/npcs.js +55 -9
  169. package/kits/hub-game/code/server/observe.js +67 -6
  170. package/kits/hub-game/code/server/players.js +8 -1
  171. package/kits/hub-game/code/server/replay.js +135 -0
  172. package/kits/hub-game/code/server/storageLimit.js +4 -1
  173. package/kits/hub-game/code/server/townDay.js +74 -0
  174. package/kits/hub-game/code/server/trackQueue.js +29 -0
  175. package/kits/hub-game/code/server/vehicle.js +3 -0
  176. package/kits/hub-game/code/server/vis.js +26 -4
  177. package/kits/hub-game/code/server/wallet.js +677 -0
  178. package/kits/hub-game/code/server/wear.js +13 -3
  179. package/kits/hub-game/code/server/writerLease.js +191 -0
  180. package/kits/hub-game/code/shared/act.js +1 -1
  181. package/kits/hub-game/code/shared/expression.js +6 -0
  182. package/kits/hub-game/code/shared/replay.js +37 -0
  183. package/kits/hub-game/code/systems/hub.js +437 -57
  184. package/kits/hub-game/docs/analytics.md +20 -3
  185. package/kits/hub-game/docs/contract.md +942 -99
  186. package/kits/hub-game/docs/home-pieces.md +5 -6
  187. package/kits/hub-game/docs/observed-progress.md +49 -1
  188. package/kits/hub-game/docs/vehicle-preset.md +23 -0
  189. package/kits/hub-game/index.html +1 -0
  190. package/kits/hub-game/models/hats/baker-cap.pxmodel +3 -3
  191. package/kits/hub-game/models/hats/bat-clip.pxmodel +3 -3
  192. package/kits/hub-game/models/hats/beekeeper.pxmodel +3 -3
  193. package/kits/hub-game/models/hats/cap.pxmodel +3 -3
  194. package/kits/hub-game/models/hats/captain.pxmodel +3 -3
  195. package/kits/hub-game/models/hats/chef-toque.pxmodel +3 -3
  196. package/kits/hub-game/models/hats/crooked-top.pxmodel +3 -3
  197. package/kits/hub-game/models/hats/delivery-cap.pxmodel +3 -3
  198. package/kits/hub-game/models/hats/fire-helmet.pxmodel +3 -3
  199. package/kits/hub-game/models/hats/flower-crown.pxmodel +3 -3
  200. package/kits/hub-game/models/hats/foam-crown.pxmodel +3 -3
  201. package/kits/hub-game/models/hats/hard-hat.pxmodel +3 -3
  202. package/kits/hub-game/models/hats/lantern.pxmodel +3 -3
  203. package/kits/hub-game/models/hats/laurel.pxmodel +3 -3
  204. package/kits/hub-game/models/hats/lighthouse.pxmodel +3 -3
  205. package/kits/hub-game/models/hats/nurse-cap.pxmodel +3 -3
  206. package/kits/hub-game/models/hats/police-cap.pxmodel +3 -3
  207. package/kits/hub-game/models/hats/sailor.pxmodel +3 -3
  208. package/kits/hub-game/models/hats/souwester.pxmodel +3 -3
  209. package/kits/hub-game/models/hats/straw.pxmodel +3 -3
  210. package/kits/hub-game/models/hats/sunflower.pxmodel +3 -3
  211. package/kits/hub-game/models/hats/sweatband.pxmodel +3 -3
  212. package/kits/hub-game/models/hats/teacher-beret.pxmodel +3 -3
  213. package/kits/hub-game/models/hats/witch.pxmodel +3 -3
  214. package/kits/hub-game/models/hold-show/daisy.pxmodel +231 -0
  215. package/kits/hub-game/models/hold-show/moonflower.pxmodel +171 -0
  216. package/kits/hub-game/models/hold-show/rose.pxmodel +191 -0
  217. package/kits/hub-game/models/hold-show/square/daisy.pxmodel +233 -0
  218. package/kits/hub-game/models/hold-show/square/moonflower.pxmodel +173 -0
  219. package/kits/hub-game/models/hold-show/square/rose.pxmodel +193 -0
  220. package/kits/hub-game/models/hold-show/square/sunflower.pxmodel +313 -0
  221. package/kits/hub-game/models/hold-show/square/tulip.pxmodel +133 -0
  222. package/kits/hub-game/models/hold-show/sunflower.pxmodel +311 -0
  223. package/kits/hub-game/models/hold-show/tulip.pxmodel +131 -0
  224. package/kits/hub-game/package-lock.json +3 -3
  225. package/kits/hub-game/package.json +4 -3
  226. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +1 -0
  227. package/kits/hub-game/scripts/fixtures/hud-surface.json +12 -12
  228. package/kits/hub-game/scripts/fixtures/talk-surface.json +8 -8
  229. package/kits/hub-game/scripts/gen-hats.mjs +1 -1
  230. package/kits/hub-game/scripts/gen-hold-show.mjs +27 -0
  231. package/kits/hub-game/scripts/pack.mjs +89 -23
  232. package/kits/hub-game/scripts/test-act-client.mjs +5 -0
  233. package/kits/hub-game/scripts/test-act-core.mjs +32 -0
  234. package/kits/hub-game/scripts/test-act-gate.mjs +186 -0
  235. package/kits/hub-game/scripts/test-action-rail-crowded-dom.mjs +7 -1
  236. package/kits/hub-game/scripts/test-action-rail-default-dom.mjs +102 -0
  237. package/kits/hub-game/scripts/test-action-rail-never-silent-dom.mjs +50 -0
  238. package/kits/hub-game/scripts/test-action-rail-surface.mjs +368 -0
  239. package/kits/hub-game/scripts/test-action-rail-town-jobs-dom.mjs +118 -0
  240. package/kits/hub-game/scripts/test-actions-client.mjs +5 -3
  241. package/kits/hub-game/scripts/test-actions.mjs +24 -0
  242. package/kits/hub-game/scripts/test-actors.mjs +19 -0
  243. package/kits/hub-game/scripts/test-again-corner-dom.mjs +59 -0
  244. package/kits/hub-game/scripts/test-analytics.mjs +80 -1
  245. package/kits/hub-game/scripts/test-arrival-pose-server.mjs +25 -8
  246. package/kits/hub-game/scripts/test-ask-client.mjs +9 -0
  247. package/kits/hub-game/scripts/test-ask-surface.mjs +188 -0
  248. package/kits/hub-game/scripts/test-attention.mjs +43 -1
  249. package/kits/hub-game/scripts/test-ballot-sheet-dom.mjs +71 -0
  250. package/kits/hub-game/scripts/test-ballot-surface.mjs +276 -0
  251. package/kits/hub-game/scripts/test-ballot.mjs +420 -3
  252. package/kits/hub-game/scripts/test-ban-join.mjs +1 -1
  253. package/kits/hub-game/scripts/test-celebrate-client.mjs +62 -0
  254. package/kits/hub-game/scripts/test-celebrate.mjs +116 -0
  255. package/kits/hub-game/scripts/test-chat.mjs +73 -0
  256. package/kits/hub-game/scripts/test-companion-client.mjs +203 -21
  257. package/kits/hub-game/scripts/test-companion.mjs +110 -3
  258. package/kits/hub-game/scripts/test-control-layout-dom.mjs +57 -10
  259. package/kits/hub-game/scripts/test-corner-surface.mjs +268 -0
  260. package/kits/hub-game/scripts/test-decor-client.mjs +59 -3
  261. package/kits/hub-game/scripts/test-decor.mjs +27 -0
  262. package/kits/hub-game/scripts/test-device-class.mjs +4 -1
  263. package/kits/hub-game/scripts/test-disguise-client.mjs +281 -0
  264. package/kits/hub-game/scripts/test-disguise.mjs +176 -0
  265. package/kits/hub-game/scripts/test-dock-surface.mjs +404 -0
  266. package/kits/hub-game/scripts/test-door-analytics.mjs +1 -1
  267. package/kits/hub-game/scripts/test-door-stay-client.mjs +602 -0
  268. package/kits/hub-game/scripts/test-door-stay.mjs +613 -0
  269. package/kits/hub-game/scripts/test-earned-client.mjs +119 -0
  270. package/kits/hub-game/scripts/test-emote-surface.mjs +616 -0
  271. package/kits/hub-game/scripts/test-fps-telemetry.mjs +39 -4
  272. package/kits/hub-game/scripts/test-friend-bests.mjs +38 -12
  273. package/kits/hub-game/scripts/test-ghost-click-dom.mjs +75 -0
  274. package/kits/hub-game/scripts/test-grab-client.mjs +29 -2
  275. package/kits/hub-game/scripts/test-grab-orbit.mjs +260 -11
  276. package/kits/hub-game/scripts/test-grab.mjs +10 -1
  277. package/kits/hub-game/scripts/test-hats.mjs +28 -0
  278. package/kits/hub-game/scripts/test-held-offers.mjs +394 -0
  279. package/kits/hub-game/scripts/test-high-only.mjs +3 -3
  280. package/kits/hub-game/scripts/test-hold-show-client.mjs +175 -0
  281. package/kits/hub-game/scripts/test-hold-show.mjs +355 -0
  282. package/kits/hub-game/scripts/test-hub-controls.mjs +3 -1
  283. package/kits/hub-game/scripts/test-hub-idle.mjs +348 -0
  284. package/kits/hub-game/scripts/test-hub-leaving.mjs +21 -0
  285. package/kits/hub-game/scripts/test-hub-ops.mjs +147 -0
  286. package/kits/hub-game/scripts/test-hub-trip.mjs +260 -5
  287. package/kits/hub-game/scripts/test-hud-clear.mjs +83 -0
  288. package/kits/hub-game/scripts/test-hud-rate.mjs +2 -1
  289. package/kits/hub-game/scripts/test-idle.mjs +160 -0
  290. package/kits/hub-game/scripts/test-invites-client.mjs +53 -0
  291. package/kits/hub-game/scripts/test-labels.mjs +11 -0
  292. package/kits/hub-game/scripts/test-landscape-layout.mjs +20 -0
  293. package/kits/hub-game/scripts/test-load-abandon.mjs +2 -2
  294. package/kits/hub-game/scripts/test-loading-cover.mjs +67 -1
  295. package/kits/hub-game/scripts/test-manifest.mjs +27 -0
  296. package/kits/hub-game/scripts/test-menu-client.mjs +55 -6
  297. package/kits/hub-game/scripts/test-menu-surface.mjs +236 -0
  298. package/kits/hub-game/scripts/test-npcs.mjs +128 -0
  299. package/kits/hub-game/scripts/test-observed.mjs +171 -3
  300. package/kits/hub-game/scripts/test-pack.mjs +166 -0
  301. package/kits/hub-game/scripts/test-picker-surface.mjs +321 -0
  302. package/kits/hub-game/scripts/test-placeat-server.mjs +395 -0
  303. package/kits/hub-game/scripts/test-placement-cache.mjs +1 -1
  304. package/kits/hub-game/scripts/test-pointer-clear-dom.mjs +82 -0
  305. package/kits/hub-game/scripts/test-progress-reset.mjs +184 -6
  306. package/kits/hub-game/scripts/test-push-visit.mjs +9 -0
  307. package/kits/hub-game/scripts/test-quality.mjs +312 -9
  308. package/kits/hub-game/scripts/test-quick-chat-surface.mjs +511 -0
  309. package/kits/hub-game/scripts/test-rehello.mjs +237 -0
  310. package/kits/hub-game/scripts/test-rejoin-yaw.mjs +138 -0
  311. package/kits/hub-game/scripts/test-relations-among.mjs +13 -7
  312. package/kits/hub-game/scripts/test-relations-refresh.mjs +90 -2
  313. package/kits/hub-game/scripts/test-replay-client.mjs +110 -0
  314. package/kits/hub-game/scripts/test-replay.mjs +178 -0
  315. package/kits/hub-game/scripts/test-resume-held.mjs +13 -0
  316. package/kits/hub-game/scripts/test-resume-pose-server.mjs +43 -5
  317. package/kits/hub-game/scripts/test-resync.mjs +13 -0
  318. package/kits/hub-game/scripts/test-role-client.mjs +10 -3
  319. package/kits/hub-game/scripts/test-safe-act.mjs +233 -0
  320. package/kits/hub-game/scripts/test-safe-caption.mjs +364 -0
  321. package/kits/hub-game/scripts/test-safe-layout.mjs +79 -0
  322. package/kits/hub-game/scripts/test-safe-prompt.mjs +163 -0
  323. package/kits/hub-game/scripts/test-sound-surface.mjs +256 -0
  324. package/kits/hub-game/scripts/test-soundscape.mjs +85 -2
  325. package/kits/hub-game/scripts/test-stuck-surface.mjs +174 -0
  326. package/kits/hub-game/scripts/test-stuck.mjs +31 -0
  327. package/kits/hub-game/scripts/test-talk-surface.mjs +23 -6
  328. package/kits/hub-game/scripts/test-talk-walk-dom.mjs +123 -0
  329. package/kits/hub-game/scripts/test-text-ask-surface.mjs +273 -0
  330. package/kits/hub-game/scripts/test-tiers.mjs +453 -3
  331. package/kits/hub-game/scripts/test-toast-no-row-dom.mjs +71 -0
  332. package/kits/hub-game/scripts/test-together.mjs +11 -0
  333. package/kits/hub-game/scripts/test-town-day.mjs +90 -0
  334. package/kits/hub-game/scripts/test-track-queue.mjs +64 -0
  335. package/kits/hub-game/scripts/test-try-on.mjs +39 -0
  336. package/kits/hub-game/scripts/test-ui-dom-dom.mjs +49 -2
  337. package/kits/hub-game/scripts/test-ui-tree.mjs +28 -0
  338. package/kits/hub-game/scripts/test-vehicle-client.mjs +77 -1
  339. package/kits/hub-game/scripts/test-vis.mjs +145 -0
  340. package/kits/hub-game/scripts/test-wallet.mjs +650 -0
  341. package/kits/hub-game/scripts/test-weakest-tier.mjs +135 -1
  342. package/kits/hub-game/scripts/test-world-labels.mjs +380 -0
  343. package/kits/hub-game/scripts/test-writer-lease-server.mjs +234 -0
  344. package/kits/hub-game/scripts/test-writer-lease.mjs +281 -0
  345. package/kits/hub-game/scripts/writer-storage-fixture.mjs +37 -0
  346. package/kits/hub-game/tools/hubScene/export.mjs +6 -5
  347. package/kits/hub-game/tools/hubScene/hubdata.mjs +10 -0
  348. package/kits/hub-game/tools/hubScene/test/export-fixture.mjs +48 -2
  349. package/kits/hub-game/tools/hubScene/validate-manifest.mjs +21 -3
  350. package/kits/multiplayer-3d/castle.json +5 -5
  351. package/kits/multiplayer-3d/code/client/resumeGate.js +49 -2
  352. package/kits/multiplayer-3d/code/server/ownership.js +25 -6
  353. package/kits/multiplayer-3d/code/server/world.js +19 -4
  354. package/kits/multiplayer-3d/code/systems/multiplayer.js +67 -11
  355. package/kits/multiplayer-3d/package-lock.json +1 -1
  356. package/kits/multiplayer-3d/package.json +2 -1
  357. package/kits/multiplayer-3d/scripts/test-ground-half.mjs +56 -0
  358. package/kits/multiplayer-3d/scripts/test-join-watchdog.mjs +54 -3
  359. package/kits/multiplayer-3d/scripts/test-owned-moves.mjs +190 -0
  360. package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +191 -5
  361. package/kits/multiplayer-3d/scripts/test-resync-reconnect.mjs +68 -0
  362. package/kits/physics-2d/castle.json +2 -2
  363. package/kits/physics-2d/engine/scene.js +10 -2
  364. package/kits/physics-3d/CLAUDE.md +14 -0
  365. package/kits/physics-3d/behaviors/Player.jsx +39 -3
  366. package/kits/physics-3d/castle.json +3 -3
  367. package/kits/physics-3d/docs/engine-model-cache.md +109 -0
  368. package/kits/physics-3d/docs/engine-player.md +76 -0
  369. package/kits/physics-3d/docs/engine-skip-work.md +16 -0
  370. package/kits/physics-3d/docs/pxmodel-format.md +5 -1
  371. package/kits/physics-3d/engine3d/gait.js +16 -8
  372. package/kits/physics-3d/engine3d/groundsize.js +23 -0
  373. package/kits/physics-3d/engine3d/kithooks.js +50 -0
  374. package/kits/physics-3d/engine3d/look.js +110 -17
  375. package/kits/physics-3d/engine3d/lookbake.js +19 -1
  376. package/kits/physics-3d/engine3d/materialpresets.js +3 -2
  377. package/kits/physics-3d/engine3d/modelcache.js +280 -0
  378. package/kits/physics-3d/engine3d/modelcachedigest.js +37 -0
  379. package/kits/physics-3d/engine3d/modelcachegate.js +69 -0
  380. package/kits/physics-3d/engine3d/modelrefs.js +13 -0
  381. package/kits/physics-3d/engine3d/optimize.js +20 -9
  382. package/kits/physics-3d/engine3d/playerRun.js +26 -1
  383. package/kits/physics-3d/engine3d/pxmodel.js +7 -3
  384. package/kits/physics-3d/engine3d/templatecache.js +722 -0
  385. package/kits/physics-3d/engine3d/world3d.js +211 -17
  386. package/kits/physics-3d/package-lock.json +1 -1
  387. package/kits/physics-3d/package.json +2 -1
  388. package/kits/physics-3d/play/behaviors/Player.js +43 -3
  389. package/kits/physics-3d/scripts/render.mjs +56 -8
  390. package/kits/physics-3d/scripts/template-cache-fixtures.mjs +37 -0
  391. package/kits/physics-3d/scripts/template-cache-v1-bytes.json +49 -0
  392. package/kits/physics-3d/scripts/test-gait.mjs +53 -9
  393. package/kits/physics-3d/scripts/test-ground-half.mjs +120 -0
  394. package/kits/physics-3d/scripts/test-model-cache.mjs +600 -0
  395. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +1 -0
  396. package/kits/physics-3d/scripts/test-sleeping-models.mjs +384 -0
  397. package/kits/physics-3d/scripts/test-template-cache-minified.mjs +106 -0
  398. package/kits/physics-3d/scripts/test-template-cache.mjs +519 -0
  399. package/kits/physics-3d/scripts/test-wall-slide.mjs +272 -0
  400. package/kits/physics-3d/systems/physics3d.js +51 -2
  401. package/kits/real-time/castle.json +2 -2
  402. package/kits/real-time/code/client/connection.js +3 -0
  403. package/package.json +2 -2
  404. package/vendor/three/examples/jsm/libs/fflate.module.js +2672 -0
@@ -17,7 +17,7 @@
17
17
 
18
18
  import * as THREE from 'three';
19
19
  import { queueLookBake } from './lookbake';
20
- import { markKitHooks } from './kithooks';
20
+ import { markKitHooks, recordTemplateHook, templateCaptureActive } from './kithooks';
21
21
 
22
22
  export const LOOK_DEFAULTS = {
23
23
  outline: 0.012,
@@ -102,7 +102,7 @@ export function lookIsEnabled() {
102
102
  return lookEnabled;
103
103
  }
104
104
 
105
- export function applyLook(root, model) {
105
+ export function applyLook(root, model, file = '') {
106
106
  if (!later) {
107
107
  lookNow(root, model);
108
108
  return;
@@ -113,6 +113,7 @@ export function applyLook(root, model) {
113
113
  later.waiting = waiting;
114
114
  later.merged = [];
115
115
  lookNow(root, model);
116
+ if (templateCaptureActive && waiting.occlusion) waiting.occlusion.file = file;
116
117
  queueWaiting(waiting);
117
118
  }
118
119
 
@@ -172,7 +173,7 @@ varying float vLookOcclusion;
172
173
 
173
174
  // Occlusion scales the surface color. The rim is added light, strongest where
174
175
  // the surface turns edge-on to the camera, in a lighter shade of the surface.
175
- function patchMaterial(material, look, geometry) {
176
+ export function patchMaterial(material, look, geometry) {
176
177
  if (material.userData.lookPatched) {
177
178
  return;
178
179
  }
@@ -211,6 +212,7 @@ function patchMaterial(material, look, geometry) {
211
212
  };
212
213
  material.customProgramCacheKey = () => `look|${previousKey.call(material)}`;
213
214
  markKitHooks(material, previous, previousKey);
215
+ if (templateCaptureActive) recordTemplateHook(material, { kind: 'look', look: { ...look } }, previous, previousKey);
214
216
  material.needsUpdate = true;
215
217
  }
216
218
 
@@ -238,7 +240,7 @@ function wantsOutline(mesh) {
238
240
 
239
241
  // The outline never takes a raycast hit, so picking finds the part itself.
240
242
  // Clones stay outlines, since a clone is made with the same constructor.
241
- class OutlineMesh extends THREE.Mesh {
243
+ export class OutlineMesh extends THREE.Mesh {
242
244
  raycast() {}
243
245
  }
244
246
 
@@ -288,8 +290,21 @@ function makeOutline(geometry, look, partMaterial) {
288
290
  material.map = cut.map;
289
291
  material.alphaTest = cut.alphaTest;
290
292
  }
293
+ patchOutlineMaterial(material, look.outline);
294
+ if (waits) {
295
+ waitForOutline(geometry, material);
296
+ }
297
+ const outline = new OutlineMesh(geometry, material);
298
+ outline.userData.lookOutline = true;
299
+ outline.castShadow = false;
300
+ outline.receiveShadow = false;
301
+ return outline;
302
+ }
303
+
304
+ // Recreate the same closure for a cached outline, without touching geometry.
305
+ export function patchOutlineMaterial(material, width) {
291
306
  const uniforms = {
292
- lookOutline: { value: look.outline },
307
+ lookOutline: { value: width },
293
308
  lookViewportHeight: { value: 720 },
294
309
  };
295
310
  material.onBeforeCompile = (shader) => {
@@ -304,14 +319,7 @@ function makeOutline(geometry, look, partMaterial) {
304
319
  renderer.getCurrentViewport(viewport);
305
320
  uniforms.lookViewportHeight.value = Math.max(1, viewport.w / renderer.getPixelRatio());
306
321
  };
307
- if (waits) {
308
- waitForOutline(geometry, material);
309
- }
310
- const outline = new OutlineMesh(geometry, material);
311
- outline.userData.lookOutline = true;
312
- outline.castShadow = false;
313
- outline.receiveShadow = false;
314
- return outline;
322
+ if (templateCaptureActive) recordTemplateHook(material, { kind: 'outline', width });
315
323
  }
316
324
 
317
325
  // Two attributes for the hull. `lookOutlineNormal` is the normal averaged
@@ -800,11 +808,15 @@ let later = null;
800
808
 
801
809
  // Runs `build`, which builds a model; the baking its look needs is queued on
802
810
  // `queue` (lookbake.js) as `owner`'s instead of being done.
803
- export function bakingLater(queue, owner, build) {
811
+ export function bakingLater(queue, owner, build, restoreTemplate = false) {
804
812
  const outer = later;
805
813
  later = { queue, owner, waiting: null, merged: [] };
814
+ if (templateCaptureActive || restoreTemplate) later.templates = [];
806
815
  try {
807
- return build();
816
+ const root = build();
817
+ if (restoreTemplate) queueTemplateLook(root);
818
+ if (later.templates) (templateBakes ??= new WeakMap()).set(root, later.templates);
819
+ return root;
808
820
  } finally {
809
821
  later = outer;
810
822
  }
@@ -815,6 +827,84 @@ export function bakingLater(queue, owner, build) {
815
827
  // parts, where each part lies in it.
816
828
  const outlinesWaiting = new WeakMap();
817
829
  const mergedParts = new WeakMap();
830
+ let templateBakes, restoredBakes, templateClones;
831
+
832
+ // Pristine deferred work is data: geometry/material references, the original
833
+ // placements and merged-part ranges. No generator or gameplay state is stored.
834
+ export function templateLookBakes(root) {
835
+ const restored = restoredBakes?.get(root);
836
+ if (restored) return restored;
837
+ return (templateBakes?.get(root) ?? []).filter(({ queue, task }) => queue.tasks.includes(task)).map(({ waiting, task }) => {
838
+ if (task.started) throw new Error('pending look bake already started');
839
+ return { task, occlusion: waiting.occlusion,
840
+ outlines: waiting.outlines.map((geometry) => ({ geometry, parts: mergedParts.get(geometry) ?? null,
841
+ materials: [...(outlinesWaiting.get(geometry) ?? [])] })),
842
+ copies: [...task.copyOf], gone: [...task.gone] };
843
+ });
844
+ }
845
+
846
+ export function templateLookClone(material) {
847
+ return templateClones?.has(material) && templateClones.get(material) === material.clone;
848
+ }
849
+
850
+ export function restoreTemplateLook(root, recipes) {
851
+ if (recipes.length) (restoredBakes ??= new WeakMap()).set(root, recipes);
852
+ }
853
+
854
+ // A deserialized model is a value copy, but the page's AO cache is keyed by
855
+ // the builder's parsed model identity, including referenced models.
856
+ export function bindTemplateLookModels(root, resolve) {
857
+ for (const { occlusion } of restoredBakes?.get(root) ?? []) {
858
+ if (!occlusion) continue;
859
+ const model = resolve(occlusion.file);
860
+ if (!model) return false;
861
+ const cached = occlusionCache.get(model);
862
+ // Degenerate surfaces can cache null instead of an AO attribute. Rebuild
863
+ // those rather than replaying a stale shader/attribute combination.
864
+ if (cached?.shape === occlusion.shape && occlusion.targets.some(({ geometry }, index) =>
865
+ !cached.values[index] || cached.values[index].length !== geometry.getAttribute('position').count)) return false;
866
+ occlusion.model = model;
867
+ }
868
+ return true;
869
+ }
870
+
871
+ // Play keeps the frozen bytes, not references to completed tasks and their
872
+ // source geometries. Dropping capture metadata never cancels queued work.
873
+ export function forgetTemplateLook(root) {
874
+ templateBakes?.delete(root);
875
+ }
876
+
877
+ function queueTemplateLook(root) {
878
+ for (const recipe of restoredBakes?.get(root) ?? []) {
879
+ let occlusion = recipe.occlusion;
880
+ let restored = recipe;
881
+ const cached = occlusion && occlusionCache.get(occlusion.model);
882
+ if (cached && cached.shape === occlusion.shape) {
883
+ // bakeOcclusion uses cached values before copies are handed out. Give
884
+ // existing construction-time copies the independent arrays clone made.
885
+ occlusion.targets.forEach(({ geometry }, index) => {
886
+ const values = cached.values[index];
887
+ geometry.setAttribute('lookOcclusion', new THREE.BufferAttribute(values, 1));
888
+ for (const [copy, original] of recipe.copies) if (original === geometry) {
889
+ copy.setAttribute('lookOcclusion', new THREE.BufferAttribute(values.slice(), 1));
890
+ }
891
+ });
892
+ occlusion = null;
893
+ const originals = new Set(recipe.outlines.map(({ geometry }) => geometry));
894
+ const copies = recipe.copies.filter(([, original]) => originals.has(original));
895
+ const members = new Set([...originals, ...copies.map(([copy]) => copy)]);
896
+ restored = { copies, gone: recipe.gone.filter((geometry) => members.has(geometry)) };
897
+ }
898
+ for (const { geometry, parts, materials } of recipe.outlines) {
899
+ if (parts) mergedParts.set(geometry, parts);
900
+ const hidden = [];
901
+ outlinesWaiting.set(geometry, hidden);
902
+ for (const material of materials) hideUntilBaked(material, hidden);
903
+ }
904
+ queueWaiting({ occlusion, outlines: recipe.outlines.map(({ geometry }) => geometry) }, restored);
905
+ }
906
+ restoredBakes?.delete(root);
907
+ }
818
908
 
819
909
  // `parts` is what `outlinePartByPart` returned for the geometries `geometry`
820
910
  // was merged from. Its attributes are baked whether or not a hull is drawn
@@ -870,9 +960,10 @@ function hideUntilBaked(material, hidden) {
870
960
  hideUntilBaked(own, hidden);
871
961
  return own;
872
962
  };
963
+ if (templateCaptureActive || later?.templates) (templateClones ??= new WeakMap()).set(material, material.clone);
873
964
  }
874
965
 
875
- function queueWaiting(waiting) {
966
+ function queueWaiting(waiting, restored = null) {
876
967
  const { queue, owner } = later;
877
968
  later.waiting = null;
878
969
  const geometries = new Set(waiting.outlines);
@@ -894,7 +985,8 @@ function queueWaiting(waiting) {
894
985
  bake.gone = gone;
895
986
  return bakeLater(bake);
896
987
  };
897
- queueLookBake(queue, owner, [...geometries], steps, (copy, geometry, source) => copied(bake, copy, geometry, source));
988
+ const task = queueLookBake(queue, owner, [...geometries], steps, (copy, geometry, source) => copied(bake, copy, geometry, source), restored);
989
+ if (later.templates) later.templates.push({ waiting, task, queue });
898
990
  }
899
991
 
900
992
  // One task's baking (lookbake.js states what it keeps to). Of each geometry
@@ -938,6 +1030,7 @@ function settle(bake, geometry) {
938
1030
  for (const material of hidden) {
939
1031
  material.visible = true;
940
1032
  delete material.clone;
1033
+ templateClones?.delete(material);
941
1034
  }
942
1035
  outlinesWaiting.delete(geometry);
943
1036
  }
@@ -85,7 +85,7 @@ export function makeLookBake() {
85
85
  // `geometries`, and `copied(copy, geometry, source)` is told: `source` is
86
86
  // what it was cloned from and `geometry` the one of the task's own that
87
87
  // `source` is, or is a copy of.
88
- export function queueLookBake(queue, owner, geometries, steps, copied = null) {
88
+ export function queueLookBake(queue, owner, geometries, steps, copied = null, restored = null) {
89
89
  const gone = new Set();
90
90
  const task = { owner, geometries, gone, copyOf: new Map(), copied, steps: steps(gone), started: false, distance: 0, onDispose: null };
91
91
  task.onDispose = (event) => {
@@ -98,15 +98,33 @@ export function queueLookBake(queue, owner, geometries, steps, copied = null) {
98
98
  for (const geometry of [...geometries]) {
99
99
  waitIn(task, geometry);
100
100
  }
101
+ if (restored) {
102
+ for (const [copy, geometry] of restored.copies) {
103
+ task.copyOf.set(copy, geometry);
104
+ geometries.push(copy);
105
+ waitIn(task, copy);
106
+ copied?.(copy, geometry, geometry);
107
+ }
108
+ }
101
109
  queue.tasks.push(task);
102
110
  queue.unsorted = true;
103
111
  queue.shown = false;
112
+ if (restored) for (const geometry of restored.gone) task.onDispose({ target: geometry });
113
+ return task;
104
114
  }
105
115
 
106
116
  // The tasks each geometry waits in. While it is in any, its `clone` is
107
117
  // `cloneWaiting`, a property of its own that goes when the last task does.
108
118
  const waitingIn = new WeakMap();
109
119
 
120
+ // Only the cache's pristine bake recipes can stand in for these callbacks.
121
+ export function templateBakeGeometry(geometry, tasks) {
122
+ const waiting = waitingIn.get(geometry);
123
+ if (Object.hasOwn(geometry, 'clone') && (geometry.clone !== cloneWaiting || !waiting?.length || waiting.some((task) => !tasks.has(task)))) return false;
124
+ return Object.entries(geometry._listeners ?? {}).every(([name, listeners]) => listeners.every((listener) =>
125
+ name === 'dispose' && waiting?.some((task) => tasks.has(task) && task.onDispose === listener)));
126
+ }
127
+
110
128
  function waitIn(task, geometry) {
111
129
  geometry.addEventListener('dispose', task.onDispose);
112
130
  const tasks = waitingIn.get(geometry);
@@ -10,7 +10,7 @@
10
10
 
11
11
  import * as THREE from 'three';
12
12
  import { PART_DEFAULTS } from './pxmodel';
13
- import { markKitHooks } from './kithooks';
13
+ import { markKitHooks, recordTemplateHook, templateCaptureActive } from './kithooks';
14
14
 
15
15
  const FINISH_KEYS = ['roughness', 'metalness', 'clearcoat', 'emissive', 'emissiveIntensity'];
16
16
 
@@ -76,7 +76,7 @@ function setFinish(material, part, preset) {
76
76
 
77
77
  // Emissive light is one color for the whole material. Here it is multiplied
78
78
  // by the vertex color, so bright paint glows and dark paint barely does.
79
- function glowByColor(material) {
79
+ export function glowByColor(material) {
80
80
  material.onBeforeCompile = (shader) => {
81
81
  shader.fragmentShader = shader.fragmentShader.replace(
82
82
  '#include <emissivemap_fragment>',
@@ -85,6 +85,7 @@ function glowByColor(material) {
85
85
  };
86
86
  material.customProgramCacheKey = () => 'glow-by-color';
87
87
  markKitHooks(material);
88
+ if (templateCaptureActive) recordTemplateHook(material, { kind: 'glow' });
88
89
  }
89
90
 
90
91
  //
@@ -0,0 +1,280 @@
1
+ // Play-only, opt-in scene template cache. Storage and digest modules load only
2
+ // after the key is accepted; editor worlds never create a visit or a report.
3
+ import { templateCacheKey, serializeTemplate, deserializeTemplate, TEMPLATE_CACHE_VERSION } from './templatecache';
4
+ import { beginTemplateCapture, endTemplateCapture } from './kithooks';
5
+ import { disposeNode } from './materials';
6
+ import { bakingLater, forgetTemplateLook, bindTemplateLookModels } from './look';
7
+ import { makeLookBake, stepLookBake, clearLookBake } from './lookbake';
8
+ import { parseModelCached } from './pxmodel';
9
+
10
+ import { MODEL_CACHE_MAX_BYTES } from './modelcachegate';
11
+ export { preloadModelCache, modelCacheVisitReady, readModelCacheKey, MODEL_CACHE_DEFAULT_BYTES, MODEL_CACHE_MAX_BYTES } from './modelcachegate';
12
+ const PREFIX = 'physics-3d:model-cache:';
13
+ const encoder = new TextEncoder();
14
+ const decoder = new TextDecoder('utf-8', { fatal: true });
15
+ const storageWork = new Map();
16
+
17
+ // Old visits cannot publish an index or resurrect a blob after a newer
18
+ // digest's cleanup. Bridge operations are async and never hold a frame.
19
+ function storageTurn(index, action) {
20
+ const previous = storageWork.get(index) ?? Promise.resolve();
21
+ const next = previous.catch(() => {}).then(action);
22
+ storageWork.set(index, next);
23
+ void next.finally(() => { if (storageWork.get(index) === next) storageWork.delete(index); }).catch(() => {});
24
+ return next;
25
+ }
26
+
27
+ function capture(build) {
28
+ beginTemplateCapture();
29
+ try { return build(); } finally { endTemplateCapture(); }
30
+ }
31
+
32
+ function sameBytes(a, b) {
33
+ if (!(a instanceof ArrayBuffer) || !(b instanceof ArrayBuffer) || a.byteLength !== b.byteLength) return false;
34
+ const left = new Uint8Array(a), right = new Uint8Array(b);
35
+ return left.every((value, index) => value === right[index]);
36
+ }
37
+
38
+ export function readModelCacheBlob(bytes, scene, digest) {
39
+ if (!(bytes instanceof ArrayBuffer) || bytes.byteLength < 4 || bytes.byteLength > MODEL_CACHE_MAX_BYTES) return null;
40
+ try {
41
+ const size = new DataView(bytes).getUint32(0, true);
42
+ const header = JSON.parse(decoder.decode(new Uint8Array(bytes, 4, size)));
43
+ if (header.version !== TEMPLATE_CACHE_VERSION || header.scene !== scene || header.digest !== digest || !Array.isArray(header.entries)) return null;
44
+ const entries = new Map();
45
+ let at = 4 + size;
46
+ for (const [key, length] of header.entries) {
47
+ if (typeof key !== 'string' || !key.startsWith(`template:${TEMPLATE_CACHE_VERSION}:`) || entries.has(key) ||
48
+ !Number.isSafeInteger(length) || length <= 0 || at + length > bytes.byteLength) return null;
49
+ entries.set(key, bytes.slice(at, at + length));
50
+ at += length;
51
+ }
52
+ return at === bytes.byteLength ? entries : null;
53
+ } catch { return null; }
54
+ }
55
+
56
+ // The Map is oldest first. Charge the complete blob, including its header.
57
+ export function boundModelCache(entries, scene, digest, maxBytes) {
58
+ const header = () => encoder.encode(JSON.stringify({ version: TEMPLATE_CACHE_VERSION, scene, digest,
59
+ entries: [...entries].map(([key, bytes]) => [key, bytes.byteLength]) }));
60
+ let payload = [...entries.values()].reduce((sum, bytes) => sum + bytes.byteLength, 0);
61
+ let json = header();
62
+ while (entries.size && 4 + json.length + payload > maxBytes) {
63
+ const key = entries.keys().next().value;
64
+ payload -= entries.get(key).byteLength;
65
+ entries.delete(key);
66
+ json = header();
67
+ }
68
+ return entries.size ? { json, size: 4 + json.length + payload } : null;
69
+ }
70
+
71
+ async function blobBytes(entries, bounded, pause, cancelled) {
72
+ const bytes = new ArrayBuffer(bounded.size);
73
+ new DataView(bytes).setUint32(0, bounded.json.length, true);
74
+ new Uint8Array(bytes, 4, bounded.json.length).set(bounded.json);
75
+ let offset = 4 + bounded.json.length;
76
+ for (const template of entries.values()) {
77
+ const source = new Uint8Array(template);
78
+ for (let at = 0; at < source.length; at += 65536) {
79
+ if (cancelled()) return null;
80
+ new Uint8Array(bytes, offset + at, Math.min(65536, source.length - at)).set(source.subarray(at, at + 65536));
81
+ if (at % (512 * 1024) === 0) await pause();
82
+ }
83
+ offset += source.length;
84
+ }
85
+ return bytes;
86
+ }
87
+
88
+ const pause = () => new Promise((resolve) => setTimeout(resolve, 0));
89
+ const defaultStorage = () => import('castle-web-sdk').then((module) => module.LocalCache);
90
+
91
+ export function createModelCacheVisit(world, runtime, scene, maxBytes, options) {
92
+ return new ModelCacheVisit(world, runtime, scene, maxBytes, options);
93
+ }
94
+
95
+ class ModelCacheVisit {
96
+ constructor(world, runtime, scene, maxBytes, options = {}) {
97
+ this.world = world;
98
+ this.runtime = runtime;
99
+ this.data = runtime.data;
100
+ this.files = runtime.files;
101
+ this.scene = scene;
102
+ this.maxBytes = maxBytes;
103
+ this.options = options;
104
+ this.entries = new Map();
105
+ this.pending = new Map();
106
+ this.closed = false;
107
+ this.ready = false;
108
+ this.dirty = false;
109
+ this.revision = 0;
110
+ this.firstFrame = false;
111
+ this.timer = null;
112
+ this.running = null;
113
+ this.report = options.report ?? { hits: 0, misses: 0, stored: 0, bytes: 0, readMs: 0, decodeMs: 0 };
114
+ if (globalThis.__castleModelCacheVerify === true) Object.assign(this.report, { verified: 0, mismatches: [] });
115
+ }
116
+
117
+ async preload() {
118
+ const started = performance.now();
119
+ let timer;
120
+ // Include lazy module/digest work in the 1500 ms allowance. The task
121
+ // returns data only: a timed-out or abandoned read cannot adopt anything.
122
+ const task = (async () => {
123
+ const digest = this.options.digest;
124
+ if (typeof digest !== 'string' || !digest || this.closed || this.readExpired) return null;
125
+ const storage = await (this.options.localCache ?? defaultStorage());
126
+ if (this.closed || this.readExpired) return null;
127
+ this.storage = storage;
128
+ this.digest = digest;
129
+ this.indexKey = `${PREFIX}${encodeURIComponent(this.scene)}:index`;
130
+ this.blobKey = `${PREFIX}${encodeURIComponent(this.scene)}:${digest}`;
131
+ const [blob, old] = await Promise.all([storage.getBinary(this.blobKey), storage.getText(this.indexKey)]);
132
+ return { blob, old };
133
+ })().catch(() => null);
134
+ const timeout = new Promise((resolve) => { timer = setTimeout(() => resolve(null), this.options.timeoutMs ?? 1500); });
135
+ const result = await Promise.race([task, timeout]);
136
+ clearTimeout(timer);
137
+ if (this.readExpired) return;
138
+ this.readExpired = true;
139
+ if (this.closed) return;
140
+ this.report.readMs = performance.now() - started;
141
+ if (result) {
142
+ const entries = readModelCacheBlob(result.blob, this.scene, this.digest);
143
+ if (entries) { this.entries = entries; this.report.bytes = result.blob.byteLength; this.report.stored = entries.size; }
144
+ else if (result.blob) this.dirty = true;
145
+ if (result.blob?.byteLength > this.maxBytes) this.dirty = true;
146
+ if (typeof result.old === 'string' && result.old.startsWith(`${PREFIX}${encodeURIComponent(this.scene)}:`) && result.old !== this.blobKey) {
147
+ this.dirty = true;
148
+ void storageTurn(this.indexKey, () => this.storage.remove(result.old)).catch(() => {});
149
+ }
150
+ }
151
+ this.ready = true;
152
+ }
153
+
154
+ template(_sharedKey, file, model, sprites, files, drops, build, buildAsScene, later = this.world.bakesLookLater) {
155
+ this.revision++;
156
+ const key = templateCacheKey(files[file], file, { models: files, sprites, optimize: true,
157
+ dropEmptyParts: drops === true, bakesLookLater: later === true,
158
+ skipSurfaceBakes: this.world.lookBake?.skipSurfaceBakes === true });
159
+ const bytes = this.entries.get(key);
160
+ if (bytes) {
161
+ const started = performance.now();
162
+ const decode = () => {
163
+ const root = deserializeTemplate(bytes);
164
+ if (root && !bindTemplateLookModels(root, (path) => path === file ? model : parseModelCached(files[path]))) {
165
+ disposeNode(root);
166
+ return null;
167
+ }
168
+ return root;
169
+ };
170
+ const root = decode();
171
+ this.report.decodeMs += performance.now() - started;
172
+ let verified = true;
173
+ let fresh;
174
+ if (root && this.report.mismatches) {
175
+ const queue = makeLookBake();
176
+ queue.now = () => 0;
177
+ queue.skipSurfaceBakes = this.world.lookBake?.skipSurfaceBakes === true;
178
+ // QA may finish isolated copies, while the actual hit remains exactly
179
+ // the unbaked build result that the playing world's queue will receive.
180
+ const proof = later ? bakingLater(queue, key, decode, true) : root;
181
+ try {
182
+ fresh = capture(() => later ? bakingLater(queue, key, build) : build());
183
+ while (queue.pending > 0) stepLookBake(queue);
184
+ this.report.verified++;
185
+ verified = sameBytes(serializeTemplate(proof).bytes, serializeTemplate(fresh).bytes);
186
+ if (!verified) this.report.mismatches.push(key);
187
+ } finally {
188
+ clearLookBake(queue);
189
+ if (proof !== root) disposeNode(proof);
190
+ }
191
+ }
192
+ if (root && verified) {
193
+ if (fresh) disposeNode(fresh);
194
+ this.entries.delete(key);
195
+ this.entries.set(key, bytes);
196
+ this.report.hits++;
197
+ this.dirty = true;
198
+ const template = buildAsScene ? buildAsScene(() => root, true) : root;
199
+ forgetTemplateLook(template);
200
+ return template;
201
+ }
202
+ if (root) disposeNode(root);
203
+ if (fresh) disposeNode(fresh);
204
+ this.entries.delete(key);
205
+ this.dirty = true;
206
+ }
207
+ this.report.misses++;
208
+ return capture(() => {
209
+ const root = buildAsScene ? buildAsScene(build) : build();
210
+ // Freeze bytes synchronously, inside capture and before takeModel can
211
+ // hand any copy to play. No material, geometry or node is read at flush.
212
+ const { bytes } = serializeTemplate(root);
213
+ forgetTemplateLook(root);
214
+ if (bytes) this.pending.set(key, bytes);
215
+ this.dirty = true;
216
+ return root;
217
+ });
218
+ }
219
+
220
+ afterFrame() {
221
+ if (!this.firstFrame) {
222
+ this.firstFrame = true;
223
+ this.noLoadDue = performance.now() + (this.options.settleMs ?? 3000);
224
+ }
225
+ if (this.closed || !this.ready || !this.dirty || this.timer !== null || this.running) return;
226
+ const load = this.world.modelLoad;
227
+ if (load && !load.restMarked) return;
228
+ // No load queue: wait three seconds after the first drawn frame.
229
+ const delay = load?.restMarked ? 0 : Math.max(0, this.noLoadDue - performance.now());
230
+ this.timer = setTimeout(() => { this.timer = null; void this.flush(); }, delay);
231
+ }
232
+
233
+ async flush() {
234
+ if (this.running) return this.running;
235
+ if (!this.firstFrame || !this.ready || this.closed || this.world.modelLoad && !this.world.modelLoad.restMarked) return;
236
+ if (this.timer !== null) { clearTimeout(this.timer); this.timer = null; }
237
+ this.running = this.write().catch(() => {}).finally(() => { this.running = null; });
238
+ return this.running;
239
+ }
240
+
241
+ async write() {
242
+ const cancelled = () => this.closed || this.world.disposed || this.world.modelCache !== this;
243
+ const yieldTurn = this.options.pause ?? pause;
244
+ const revision = this.revision;
245
+ if (!this.storage || !this.blobKey) { this.pending.clear(); this.dirty = false; return; }
246
+ const batch = [...this.pending];
247
+ for (const [key, bytes] of batch) {
248
+ if (cancelled()) return;
249
+ if (this.pending.get(key) === bytes) this.pending.delete(key);
250
+ this.entries.delete(key);
251
+ this.entries.set(key, bytes);
252
+ await yieldTurn();
253
+ }
254
+ if (cancelled() || !this.storage || !this.blobKey) return;
255
+ const writing = new Map(this.entries);
256
+ const bounded = boundModelCache(writing, this.scene, this.digest, this.maxBytes);
257
+ for (const [key, bytes] of this.entries) if (!writing.has(key) && this.entries.get(key) === bytes) this.entries.delete(key);
258
+ const blob = bounded ? await blobBytes(writing, bounded, yieldTurn, cancelled) : null;
259
+ if (cancelled()) return;
260
+ this.dirty = this.pending.size > 0 || this.revision !== revision;
261
+ this.report.stored = writing.size;
262
+ this.report.bytes = blob?.byteLength ?? 0;
263
+ // set transfers its buffer. The blob is a separate allocation; the
264
+ // per-template byte arrays remain owned by this visit for future hits.
265
+ await storageTurn(this.indexKey, async () => {
266
+ if (cancelled()) return;
267
+ if (blob) await this.storage.set(this.blobKey, blob);
268
+ else await this.storage.remove(this.blobKey);
269
+ if (!cancelled()) await this.storage.set(this.indexKey, this.blobKey);
270
+ else await this.storage.remove(this.blobKey);
271
+ });
272
+ }
273
+
274
+ close() {
275
+ this.closed = true;
276
+ if (this.timer !== null) clearTimeout(this.timer);
277
+ this.pending.clear();
278
+ this.entries.clear();
279
+ }
280
+ }
@@ -0,0 +1,37 @@
1
+ // Loaded only for opted-in play. Inspect the frame's existing code, without
2
+ // bundling a second copy of the kit's source or fetching any script contents.
3
+ import * as THREE from 'three';
4
+ import { TEMPLATE_CACHE_VERSION } from './templatecache';
5
+
6
+ export async function digestModelCacheScripts(environment = globalThis) {
7
+ try {
8
+ const { document, TextEncoder, crypto } = environment;
9
+ if (!document?.scripts || typeof TextEncoder !== 'function' || typeof crypto?.subtle?.digest !== 'function') return null;
10
+ const scripts = [];
11
+ for (const script of document.scripts) {
12
+ if (script.src) {
13
+ let path;
14
+ try {
15
+ const url = new URL(script.src, document.baseURI);
16
+ if (['http:', 'https:'].includes(url.protocol)) path = url.pathname;
17
+ } catch { path = null; /* An unparseable URL is not content-addressed. */ }
18
+ if (!path || !/(?:^|\/)[a-f0-9]{64}(?:\.m?js)?(?:\/|$)/i.test(path)) {
19
+ return { digest: null, reason: 'unhashed script' };
20
+ }
21
+ scripts.push(`src:${script.src}`);
22
+ } else scripts.push(`inline:${script.textContent}`);
23
+ }
24
+ const input = new TextEncoder().encode(JSON.stringify([TEMPLATE_CACHE_VERSION, THREE.REVISION, scripts]));
25
+ const digest = await crypto.subtle.digest('SHA-256', input);
26
+ return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('').slice(0, 16);
27
+ } catch { return null; }
28
+ }
29
+
30
+ // One snapshot per page, including an unavailable result. Native hashing starts
31
+ // during preload and shares its deadline; a late result cannot enable a visit.
32
+ export function makeModelCacheBuildDigest(environment = globalThis) {
33
+ let digest;
34
+ return () => digest ??= digestModelCacheScripts(environment);
35
+ }
36
+
37
+ export const modelCacheBuildDigest = makeModelCacheBuildDigest();
@@ -0,0 +1,69 @@
1
+ // Keyless play imports only this gate: no codec, script digest or SDK module.
2
+ export const MODEL_CACHE_DEFAULT_BYTES = 8 * 1024 * 1024;
3
+ export const MODEL_CACHE_MAX_BYTES = 16 * 1024 * 1024;
4
+
5
+ export function readModelCacheKey(data) {
6
+ const key = data?.engine?.modelCache;
7
+ if (!key || typeof key !== 'object' || Array.isArray(key)) return null;
8
+ for (const name in key) if (Object.hasOwn(key, name) && name !== 'maxBytes') return null;
9
+ const maxBytes = key.maxBytes === undefined ? MODEL_CACHE_DEFAULT_BYTES : key.maxBytes;
10
+ return Number.isSafeInteger(maxBytes) && maxBytes > 0 && maxBytes <= MODEL_CACHE_MAX_BYTES ? maxBytes : null;
11
+ }
12
+
13
+ // Returns null without a valid key, otherwise the same promise for this visit.
14
+ // The timeout includes loading the optional cache/SDK/digest modules themselves.
15
+ export function preloadModelCache(world, runtime, options) {
16
+ const maxBytes = world.staticActorsOff === true || world.disposed ? null : readModelCacheKey(runtime.data);
17
+ const scene = runtime.scenePath ?? runtime.currentScenePath ?? 'scenes/main.scene';
18
+ const previous = world.modelCache;
19
+ if (previous && previous.data === runtime.data && previous.scene === scene && previous.files === runtime.files && previous.maxBytes === maxBytes && !previous.closed) return previous.readyPromise;
20
+ if (previous) { previous.close(); delete world.modelCache; delete world.modelCacheReport; }
21
+ if (!maxBytes) return null;
22
+ const started = performance.now();
23
+ const timeoutMs = options?.timeoutMs ?? 1500;
24
+ const report = { hits: 0, misses: 0, stored: 0, bytes: 0, readMs: 0, decodeMs: 0 };
25
+ if (globalThis.__castleModelCacheVerify === true) Object.assign(report, { verified: 0, mismatches: [] });
26
+ // If an optional module itself times out, ordinary builds remain available.
27
+ const waiting = { data: runtime.data, scene, files: runtime.files, maxBytes, report, ready: false, closed: false,
28
+ template(_shared, _file, _model, _sprites, _files, _drops, build, buildAsScene) { report.misses++; return buildAsScene ? buildAsScene(build) : build(); },
29
+ afterFrame() {}, close() { this.closed = true; } };
30
+ let current = waiting;
31
+ let timer;
32
+ world.modelCache = waiting;
33
+ world.modelCacheReport = report;
34
+ // Start hashing alongside optional module loading. The blob key needs the
35
+ // result; failed hashing must not issue even an index read to LocalCache.
36
+ const digest = options?.digest === undefined
37
+ ? import('./modelcachedigest').then((module) => module.modelCacheBuildDigest())
38
+ : Promise.resolve(options.digest);
39
+ const moduleReady = import('./modelcache').catch(() => null);
40
+ const loaded = digest.catch(() => null).then(async (digest) => {
41
+ if (waiting.closed || performance.now() - started >= timeoutMs) return;
42
+ if (typeof digest !== 'string' || !digest) {
43
+ report.digest = 'unavailable';
44
+ if (digest?.reason) report.reason = digest.reason;
45
+ return;
46
+ }
47
+ const module = await moduleReady;
48
+ if (!module || waiting.closed || performance.now() - started >= timeoutMs) return;
49
+ current = module.createModelCacheVisit(world, runtime, scene, maxBytes,
50
+ { ...options, digest, report, timeoutMs: Math.max(0, timeoutMs - (performance.now() - started)) });
51
+ current.readyPromise = waiting.readyPromise;
52
+ world.modelCache = current;
53
+ await current.preload();
54
+ }).catch(() => {});
55
+ const deadline = new Promise((resolve) => { timer = setTimeout(resolve, timeoutMs); });
56
+ waiting.readyPromise = Promise.race([loaded, deadline]).then(() => {
57
+ clearTimeout(timer);
58
+ if (world.modelCache !== current || current.closed) return;
59
+ current.readExpired = true;
60
+ current.ready = true;
61
+ report.readMs = performance.now() - started;
62
+ });
63
+ return waiting.readyPromise;
64
+ }
65
+
66
+ export function modelCacheVisitReady(world, runtime) {
67
+ preloadModelCache(world, runtime);
68
+ return !world.modelCache || world.modelCache.ready;
69
+ }