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
@@ -91,10 +91,46 @@ function pullSteadily(phys, actor) {
91
91
  phys.addForce(actor, { x: 0, y: -14 * phys.mass(actor), z: 0 });
92
92
  }
93
93
 
94
- function applyMove(phys, actor, move, speed, grounded, dt) {
94
+ // Clip the requested walk against at most two nearby wall planes. A second
95
+ // plane that sends the tangent back into the first is a closed corner.
96
+ // Keep the tangent's length: projecting must not speed up a diagonal walk.
97
+ function slideMove(phys, actor, move) {
98
+ const wanted = move;
99
+ let first = null;
100
+ let excludeCollider;
101
+ for (let i = 0; i < 2; i += 1) {
102
+ const length = Math.hypot(move.x, move.z);
103
+ if (length < 1e-6) return { x: 0, z: 0 };
104
+ const hit = phys.castWalkWall(actor, { x: move.x / length, y: 0, z: move.z / length }, 0.12, excludeCollider);
105
+ const n = hit?.normal;
106
+ // castWalkWall resolves convex-edge support normals to surface faces:
107
+ // adjoining boxes in a straight wall do not supply a second wall plane.
108
+ // Floors and slopes keep their existing drive; only near-vertical faces.
109
+ if (!n || Math.abs(n.y) > 0.2) break;
110
+ const horizontal = Math.hypot(n.x, n.z);
111
+ if (horizontal < 1e-6) break;
112
+ const normal = { x: n.x / horizontal, z: n.z / horizontal };
113
+ const into = move.x * normal.x + move.z * normal.z;
114
+ if (into >= -1e-6) break;
115
+ // Reproject the original request on the second plane. Projecting the
116
+ // first tangent again can create an unwanted escape along the corner
117
+ // (and drift from tiny errors in Rapier's sweep normals).
118
+ const amount = wanted.x * normal.x + wanted.z * normal.z;
119
+ move = { x: wanted.x - amount * normal.x, z: wanted.z - amount * normal.z };
120
+ if (first && move.x * first.x + move.z * first.z < -1e-6) return { x: 0, z: 0 };
121
+ first = normal;
122
+ excludeCollider = hit.colliderHandle;
123
+ }
124
+ return move;
125
+ }
126
+
127
+ function applyMove(phys, actor, move, speed, grounded, dt, scene) {
95
128
  const mass = phys.mass(actor);
96
129
  const vel = phys.getVelocity(actor);
97
130
  if (move) {
131
+ if (scene.data?.engine?.player?.slideOnWalls === true && grounded && vel.y <= 1) {
132
+ move = slideMove(phys, actor, move);
133
+ }
98
134
  const factor = Math.min(1, dt * 14) * (grounded ? 1 : 0.3);
99
135
  phys.applyImpulse(actor, {
100
136
  x: (move.x * speed - vel.x) * mass * factor,
@@ -476,7 +512,7 @@ function updateOrbiting(actor, scene, props, dt) {
476
512
  if (scene.playerDrive?.step) {
477
513
  scene.playerDrive.step(actor, phys, { keys: scene.keys, stick: scene.moveInput, grounded }, dt);
478
514
  } else {
479
- applyMove(phys, actor, driveOrbiting(scene, per, rt, props, dt), props.speed, grounded, dt);
515
+ applyMove(phys, actor, driveOrbiting(scene, per, rt, props, dt), props.speed, grounded, dt, scene);
480
516
  t.rotationY = rt.facing / DEG;
481
517
  jumpOrbiting(phys, actor, scene, rt, grounded, props.jumpSpeed, dt);
482
518
  }
@@ -1166,7 +1202,7 @@ export class Player {
1166
1202
  z: -Math.cos(per.camAngle) * drive.forward,
1167
1203
  }
1168
1204
  : null;
1169
- applyMove(phys, actor, move, this.props.speed, grounded, dt);
1205
+ applyMove(phys, actor, move, this.props.speed, grounded, dt, scene);
1170
1206
  t.rotationY = rt.facing / DEG;
1171
1207
 
1172
1208
  // Jump: Space on keyboard, or a short tap anywhere on the canvas (which
@@ -50,16 +50,16 @@
50
50
  "imports": {
51
51
  "castle.physics-2d": {
52
52
  "deckId": "ckRZGFW4iPrx",
53
- "version": "2026-10-17T06:02:29.713Z"
53
+ "version": "2026-11-15T00:41:50.817Z"
54
54
  },
55
55
  "castle.base": {
56
56
  "deckId": "yRcmH4_aYllE",
57
- "version": "2026-10-23T12:08:44.010Z"
57
+ "version": "2026-11-15T00:40:25.157Z"
58
58
  }
59
59
  },
60
60
  "main": "main.jsx",
61
61
  "autoUpdateWhenImported": true,
62
62
  "deckId": "JH0SclbPVP0y",
63
63
  "cardId": "eXfAaUdbSU5A",
64
- "publishedVersion": "2026-10-23T12:14:42.092Z"
64
+ "publishedVersion": "2026-11-18T00:50:50.040Z"
65
65
  }
@@ -0,0 +1,109 @@
1
+ # Model templates across opens
2
+
3
+ A scene may opt in with a top-level engine setting:
4
+
5
+ ```json
6
+ "engine": { "modelCache": { "maxBytes": 8388608 } }
7
+ ```
8
+
9
+ `"modelCache": {}` uses 8 MiB (8,388,608 bytes). `maxBytes` must be a
10
+ positive integer no larger than 16 MiB (16,777,216 bytes). A different shape,
11
+ unknown property or invalid value turns the key off. Without a valid key play
12
+ builds models as before, without capture or LocalCache calls. Editors and
13
+ thumbnails do not use it (`staticActorsOff`).
14
+
15
+ The cache keeps built model templates in SDK LocalCache on the player's device.
16
+ It is disposable: any read may miss, a write may store nothing, and storage may
17
+ be cleared. An unavailable, corrupt, old or unsuitable template builds normally.
18
+ A missing cache never changes scene data or prevents play.
19
+
20
+ Before the scene's first model sync, play reads one binary scene blob and one
21
+ small text index. There are no per-model bridge reads. Preload, including the
22
+ build digest, has a 1,500 ms timeout; after that this visit proceeds with all
23
+ misses, and its late read is ignored. A scene switch preloads the new scene
24
+ before its first model sync too. Gameplay updates do not run during the initial
25
+ preload. Scene loads and the first frame can therefore be later by up to that
26
+ allowance on a slow or unavailable bridge.
27
+
28
+ The blob key contains the scene path and a digest of the deck frame's code.
29
+ Once per page, native SHA-256 hashes the ordered `document.scripts` entries:
30
+ `"src:" + script.src` for content-addressed external scripts, or
31
+ `"inline:" + script.textContent` for inline scripts
32
+ (including the complete code in a single-file deck), plus the template codec
33
+ version and Three revision. The first 16 hexadecimal characters name the build.
34
+ Any deck save may invalidate the cache, including changes outside the kit. No
35
+ extra copy of kit source is bundled and no script contents are fetched.
36
+
37
+ An external script must have a complete 64-hex SHA-256 path segment, including
38
+ the CLI's `/cauldron-chunks/<sha256>.js` URLs. Any unhashed external script,
39
+ including dev-server entry/module URLs, disables caching for the visit:
40
+ `modelCacheReport.digest` is `"unavailable"` and `reason` is `"unhashed script"`.
41
+ Hashes in query strings, shortened hashes and arbitrary filenames do not qualify.
42
+
43
+ Hashing starts during preload, alongside optional module loading, within the
44
+ same 1,500 ms deadline. Storage reads wait for a successful hash. If `document`,
45
+ `document.scripts`, `TextEncoder` or `crypto.subtle` is unavailable, or hashing
46
+ fails, this visit builds normally without capture or any LocalCache calls;
47
+ `modelCacheReport.digest` is `"unavailable"`. The result, including failure, is
48
+ memoized for the page. A hash that finishes after the deadline is ignored for
49
+ that visit.
50
+
51
+ The index names the current blob, so a different digest removes the old blob
52
+ when the index is available. An index read can miss too; removal is best effort,
53
+ and SDK LocalCache still enforces its own per-deck limit.
54
+
55
+ Each template also has a key covering its model text, referenced model texts,
56
+ art state, look switch and build options. Only representable construction results
57
+ are written. Models requesting art, whether missing, loading or ready, currently
58
+ refuse caching; textures and unsupported metadata also fall back normally.
59
+
60
+ A hit supplies the same shared template that a normal build would supply to
61
+ `takeModel`. Actor copies, instancing and model release keep their usual
62
+ ownership. `engine.load` still decides which actors may wait. With
63
+ `dropEmptyParts`, the cache retains the original tree before pruning; play
64
+ prunes it normally. A miss serializes synchronously inside capture as soon as
65
+ the build returns, before any actor receives shared materials or geometry.
66
+ Later gameplay edits, including tinting, cannot change those bytes.
67
+
68
+ With deferred look baking, storage holds the unbaked construction result and a
69
+ recipe for its pending work. A hit restores that work through the normal look
70
+ queue, including merged-part outlines, placements and geometry copies. It bakes
71
+ as a fresh build does. On a same-page revisit, replay uses the current parsed
72
+ models' matching occlusion cache immediately, as a normal rebuild does, and
73
+ only queues the remaining work. Partially executed bake tasks are never serialized.
74
+
75
+ Writes happen after a frame has drawn and `load:rest-built` has settled. Without
76
+ `engine.load`, they start three seconds after the first drawn frame. Writing
77
+ uses only the bytes held since construction and may proceed while look baking
78
+ is pending. Blob copying yields in slices; bridge writes remain asynchronous.
79
+ Synchronous miss encoding adds work to a cache-enabled build. A scene left or
80
+ disposed while writing cancels the remaining work.
81
+
82
+ The budget covers the complete binary blob, including its template keys and
83
+ header. It evicts least recently used templates first, retaining their usage
84
+ order across opens. An entry too large for the budget is omitted. The small
85
+ index is separate. Other scenes and other SDK LocalCache users share the SDK's
86
+ 20 MiB per-deck allowance, so multiple scene blobs can evict each other.
87
+
88
+ `scene.three.modelCacheReport` exists for a valid key:
89
+
90
+ - `hits`, `misses`: template lookups that loaded bytes or needed a normal build.
91
+ - `stored`, `bytes`: templates and total blob bytes retained by the most recent
92
+ read/write attempt. A successful SDK set does not prove durable storage.
93
+ - `readMs`, `decodeMs`: preload time and total template decoding time.
94
+ - `digest: "unavailable"`: build hashing failed or a required browser API was
95
+ unavailable, so caching is off for this visit.
96
+ - `reason: "unhashed script"`: an external script lacked content identity.
97
+
98
+ For QA, set `globalThis.__castleModelCacheVerify = true` before opening the
99
+ scene. Every hit also builds a fresh template and compares canonical serialized
100
+ bytes. For deferred look, isolated proof copies complete their bakes before
101
+ comparison; the playing template still goes through its own queue. `verified`
102
+ counts comparisons and `mismatches` lists differing keys. A
103
+ mismatch discards the cached template and uses a normal build. These fields and
104
+ the extra builds are absent when verification is off.
105
+
106
+ Run `node scripts/test-model-cache.mjs` for the fake-bridge checks, world
107
+ lifecycle, independent hit verification and load/look/pruning/instancing cases.
108
+ `node scripts/test-template-cache-minified.mjs` bundles and minifies the codec,
109
+ builder and Three together and compares their encoded bytes with unminified builds.
@@ -0,0 +1,76 @@
1
+ # Scene key: engine.player
2
+
3
+ Opt a scene into wall sliding for the built-in `Player` walk:
4
+
5
+ ```json
6
+ {
7
+ "engine": {
8
+ "player": {
9
+ "slideOnWalls": true
10
+ }
11
+ }
12
+ }
13
+ ```
14
+
15
+ Only literal `true` enables it. Absent, `false`, or any other value preserves
16
+ all existing movement impulses and physics API calls, with no wall probes.
17
+ This applies to both tank-style walking and the orbit camera's walking.
18
+ A scene-provided `playerDrive.step` keeps its own movement rules.
19
+
20
+ When grounded and not rising from a jump, the player probes horizontally in
21
+ the requested walk direction. The probe sweeps the player's actual collider
22
+ at its current position and rotation up to 0.12 m, with a 0.01 m contact
23
+ skin. For the standard Player this is the full upright capsule, including
24
+ its lower part: a 0.5 m barrier blocks it even though a waist-height ball
25
+ would miss the barrier or meet only its top edge. Its width also catches a
26
+ grazing wall that a centre ray would miss. Only fixed solid colliders
27
+ participate: sensors, dynamic bodies, kinematic bodies, and the player
28
+ itself are excluded.
29
+
30
+ For a mostly vertical surface (`abs(normal.y) <= 0.2`), `applyMove` removes
31
+ the into-wall component of the requested horizontal velocity before its
32
+ usual walk impulse. The remaining tangent retains its projected speed; it
33
+ is not normalized back to full speed. A second probe checks the tangent
34
+ against another wall. If both planes block the walk, the target is zero,
35
+ so a corner stops the player without repeatedly pushing into either wall.
36
+ Rapier still handles collision response and existing momentum.
37
+
38
+ A shape sweep can report an oblique support normal at a convex box edge.
39
+ That normal alone would turn adjoining boxes in one straight wall into a
40
+ false closed corner. For near-vertical hits, two short rays sample either
41
+ side of the contact on the met collider (1 mm sideways, from 2 cm out).
42
+ The face normal most aligned with the sweep's support normal is used.
43
+ Thus the next box supplies the same wall plane at a straight seam; a real
44
+ perpendicular wall still supplies a blocking second plane. This also keeps
45
+ sliding across small protrusions or recesses of a few millimetres.
46
+
47
+ Upward normals at the capsule's rounded bottom are kept as reported by the
48
+ sweep, so a passable curb is not turned into a vertical wall by sampling
49
+ its side. Geometry below the hovering capsule is not swept into at all.
50
+
51
+ Floors, gentler slopes, airborne steering, jumping, the hover spring, and
52
+ camera placement keep their existing rules. No friction coefficients or
53
+ combine rules change. Removing the sustained into-wall drive is enough to
54
+ avoid the wall friction stall with the standard zero-friction Player.
55
+
56
+ The narrow physics API helper is
57
+ `scene.physics3d.castWalkWall(actor, dir, maxToi, excludeCollider?)`.
58
+ `dir` is a horizontal unit vector; `maxToi` is the sweep distance in metres.
59
+ It returns `null` or `{ distance, actorId, colliderHandle, normal }`, with
60
+ the fixed surface's world-space face normal (or the original upward contact
61
+ normal for a floor or step). The optional collider handle lets
62
+ the second probe pass the first wall. It changes no bodies or colliders.
63
+
64
+ Run `npm run test:wall-slide` in the kit (also included in `npm run check`).
65
+ It runs the real Player and physics system on the kit's vendored Rapier:
66
+ a four-second walk headed 15 degrees off a long wall's normal reproduces
67
+ the unkeyed stall, and the keyed walk retains over 90% of its open-ground
68
+ tangent distance without penetrating the wall (5 mm solver tolerance).
69
+ It also checks both walk modes, corners, more grazing headings, unchanged
70
+ open-ground trajectories, slopes, jumps, filtering, and exact pre-key
71
+ `applyMove` calls and impulse arithmetic. Regression cases cross two- and
72
+ three-box straight walls at 5 degrees off the normal, including seams
73
+ with +/-3 mm offsets, and slide along a 0.5 m barrier at 15 degrees. Curb
74
+ crossings at 2, 8, and 15 cm keep exactly the same trajectories with the key
75
+ off and on. Projection alone passes these checks with Rapier's existing
76
+ average friction combine rule.
@@ -185,3 +185,19 @@ the `engine` object at a scene file's top level, beside `ground`.
185
185
  the play scene excludes empty actors; traverse `scene.three.nodes` to find
186
186
  all actors. If the scene itself has a transform or a parent, nodes stay
187
187
  attached so world-space reads retain that transform.
188
+
189
+ 2026-10-26: `releaseModel(cache, key, dispose, park = false)` can retain a
190
+ sleeping actor's shared template with zero users; `takeModel` reuses that exact
191
+ template on wake. Actor nodes and instance bookkeeping are still removed.
192
+ Ordinary removal and signature rebuilds retain their disposal behavior. Parked
193
+ templates are cleared when no actors sleep, on scene changes/reloads, and on
194
+ world disposal. `prewarmSleepingModels(world, runtime, { budgetMs = 4, now })`
195
+ builds sleeping actors' missing templates parked, nearest the camera first,
196
+ using the same keys, empty-part variants and look-bake rules as waking. It
197
+ returns the number built and stops after crossing its time budget; an unsettled
198
+ `engine.load` pass prevents prewarming. `needsSleepingModelPrewarm(world,
199
+ runtime)` lets a caller stop invoking the builder after completion and resume
200
+ when the sleep set, a model file/reference, art readiness or build variant
201
+ changes. The runtime's `sleepVersion` and `sleepingActorCount` make sleep-set
202
+ checks cheap; older runtimes still park safely but check sleep membership to
203
+ detect changes.
@@ -872,7 +872,11 @@ drawn apart from the rest (see Cost), so move the few parts that matter.
872
872
 
873
873
  Set `"gait": "model"` at the top level of the deck's own `castle.json` to
874
874
  match walk cadence to world-space leg length (including model/actor scale).
875
- Without it, the fixed gait is unchanged. Missing legs fall back to 45% of
875
+ Without it, the fixed gait is unchanged. Model gait steps at most 2.5
876
+ stride cycles a second (two footfalls each): faster motion widens the swing
877
+ up to 0.4 rad past its base, and beyond that the feet slip rather than the
878
+ legs speed up. The torso bob shrinks once cadence passes the fixed gait's
879
+ 1.9 cycles a second. Missing legs fall back to 45% of
876
880
  visible model height, then the fixed constants if no height is measurable.
877
881
  Multiplayer-3d supplies remote cadence from network tracks; local motion,
878
882
  air poses and turn lean still follow position. Long paused frames advance
@@ -2,6 +2,13 @@
2
2
  import * as THREE from 'three';
3
3
 
4
4
  const STOP_SPEED = 0.05;
5
+ // Stride cycles a second (two footfalls each). Above it the swing widens to
6
+ // lengthen the stride, and past the widest swing the feet slip rather than
7
+ // the legs blur: short chibi legs cannot cover a hub run at a calm cadence.
8
+ const MAX_CADENCE = 2.5;
9
+ const MAX_EXTRA_SWING = 0.4;
10
+ // The fixed gait's cadence at its 5 m/s walk; torso bob shrinks above it.
11
+ const FIXED_CADENCE = 5 * 2.4 / (2 * Math.PI);
5
12
  const HINT_MAX_AGE_MS = 100;
6
13
 
7
14
  let mode = 'fixed';
@@ -86,7 +93,7 @@ function measureLegs(node, state, ids) {
86
93
  }
87
94
 
88
95
  // Both walkers use the same world-length stride and adaptive swing. Cadence,
89
- // rather than metres per second, is capped so ordinary hub running keeps up.
96
+ // rather than metres per second, is capped at MAX_CADENCE.
90
97
  // Air and lean still observe actual position and elapsed time.
91
98
  export function modelWalk(node, state, ids, baseAmplitude, observedSpeed, dt, hint) {
92
99
  const gait = measureLegs(node, state, ids);
@@ -102,19 +109,20 @@ export function modelWalk(node, state, ids, baseAmplitude, observedSpeed, dt, hi
102
109
  }
103
110
  const supplied = Number.isFinite(hint?.speed) ? hint.speed : observedSpeed;
104
111
  const speed = Number.isFinite(supplied) ? Math.max(0, Math.min(30, supplied)) : 0;
105
- const softCadence = 4.5;
106
- const amplitude = speed <= cycle * softCadence ? baseAmplitude
107
- : Math.min(baseAmplitude + 0.3, Math.asin(Math.min(1, speed / (4 * gait.length * softCadence))));
112
+ const amplitude = speed <= cycle * MAX_CADENCE ? baseAmplitude
113
+ : Math.min(baseAmplitude + MAX_EXTRA_SWING, Math.asin(Math.min(1, speed / (4 * gait.length * MAX_CADENCE))));
108
114
  const targetAmount = Math.min(1, speed / (5 * scale));
109
115
  // The rendered angle includes the swing amount. Use its target (not the
110
116
  // eased startup pose), avoiding both low-speed slip and startup spikes.
111
117
  const effectiveAmplitude = amplitude * targetAmount;
112
118
  const stride = 4 * gait.length * Math.sin(effectiveAmplitude);
113
- // This replaces the rad/metre clamp: even a tiny/broken model cannot blur
114
- // beyond six cycles a second. Division overflow also lands on this bound.
115
- const cadence = speed < STOP_SPEED ? 0 : Math.min(6, speed / stride);
119
+ // This replaces the rad/metre clamp: even a tiny/broken model cannot step
120
+ // faster than MAX_CADENCE. Division overflow also lands on this bound.
121
+ const cadence = speed < STOP_SPEED ? 0 : Math.min(MAX_CADENCE, speed / stride);
122
+ const bobScale = cadence > FIXED_CADENCE ? FIXED_CADENCE / cadence : 1;
116
123
  Object.assign(gait, { model: true, k: stride > 0 ? 2 * Math.PI / stride : 2.4, walkSpeed: 5 * scale,
117
- cap: 30, cadence, amplitude, effectiveAmplitude, targetAmount, amplitudeScale: amplitude / baseAmplitude });
124
+ cap: 30, cadence, amplitude, effectiveAmplitude, targetAmount, amplitudeScale: amplitude / baseAmplitude,
125
+ bobScale });
118
126
  return {
119
127
  ...gait,
120
128
  speed,
@@ -0,0 +1,23 @@
1
+ // A scene's optional ground size: `"ground": { "half": 150 }` is the ground's
2
+ // half-width in meters, the same on both axes, for the collider players stand
3
+ // on and for the drawn plane. Without it (or with anything but a finite
4
+ // number) a scene keeps the old ground: a 100 m half-width collider under a
5
+ // 60 m drawn plane. The value is clamped to 1..200, the edge of
6
+ // multiplayer-3d's world bounds; a native engine reads the key by this rule.
7
+
8
+ export const GROUND_HALF_MIN = 1;
9
+ export const GROUND_HALF_MAX = 200;
10
+ // The collider's half-width when a scene does not set one.
11
+ export const DEFAULT_COLLIDER_HALF = 100;
12
+
13
+ // The scene's ground half-width in meters, or null when it does not set one.
14
+ export function groundHalf(setting) {
15
+ const half = setting?.half;
16
+ if (typeof half !== 'number' || !Number.isFinite(half)) return null;
17
+ return Math.min(GROUND_HALF_MAX, Math.max(GROUND_HALF_MIN, half));
18
+ }
19
+
20
+ // The half-width of the ground collider a scene stands on.
21
+ export function colliderHalf(setting) {
22
+ return groundHalf(setting) ?? DEFAULT_COLLIDER_HALF;
23
+ }
@@ -17,6 +17,22 @@
17
17
  import * as THREE from 'three';
18
18
 
19
19
  const known = new WeakSet();
20
+ const templateHooks = new WeakMap();
21
+ const artTemplates = new WeakSet();
22
+ let captureDepth = 0;
23
+ export let templateCaptureActive = false;
24
+
25
+ // Synchronous, nestable capture. Call end in finally, including failed builds.
26
+ export function beginTemplateCapture() {
27
+ captureDepth += 1;
28
+ templateCaptureActive = true;
29
+ }
30
+
31
+ export function endTemplateCapture() {
32
+ if (captureDepth === 0) throw new Error('no template capture active');
33
+ captureDepth -= 1;
34
+ templateCaptureActive = captureDepth > 0;
35
+ }
20
36
 
21
37
  const DEFAULT_HOOK = THREE.Material.prototype.onBeforeCompile;
22
38
  const DEFAULT_KEY = THREE.Material.prototype.customProgramCacheKey;
@@ -45,3 +61,37 @@ export function markKitHooks(material, previousHook = null, previousKey = null)
45
61
  known.add(material.onBeforeCompile);
46
62
  known.add(material.customProgramCacheKey);
47
63
  }
64
+
65
+ // Private recipes keep functions and closure state out of template bytes. A
66
+ // changed or unrecorded callback is refused, even on a material the kit patched.
67
+ export function recordTemplateHook(material, recipe, previousHook = null, previousKey = null) {
68
+ if (!templateCaptureActive) return;
69
+ const previous = templateHooks.get(material);
70
+ const starts = previousHook === null || (previousHook === DEFAULT_HOOK && previousKey === DEFAULT_KEY);
71
+ const wraps = previous && previous.hook === previousHook && previous.key === previousKey;
72
+ if (!starts && !wraps) return;
73
+ if (recipe.kind !== 'outline' && material.onBeforeRender !== DEFAULT_DRAW && !(wraps && previous.draw === material.onBeforeRender)) return;
74
+ templateHooks.set(material, {
75
+ hook: material.onBeforeCompile,
76
+ key: material.customProgramCacheKey,
77
+ draw: material.onBeforeRender,
78
+ recipes: [...(starts ? [] : previous.recipes), recipe],
79
+ });
80
+ }
81
+
82
+ export function templateHookRecipes(material) {
83
+ const found = templateHooks.get(material);
84
+ if (found && found.hook === material.onBeforeCompile && found.key === material.customProgramCacheKey && found.draw === material.onBeforeRender) return found.recipes;
85
+ if (material.onBeforeCompile === DEFAULT_HOOK && material.customProgramCacheKey === DEFAULT_KEY && material.onBeforeRender === DEFAULT_DRAW) return [];
86
+ return null;
87
+ }
88
+
89
+ // Art requests must survive missing/loading textures without adding anything
90
+ // to Object3D.userData or doing model scans in normal play.
91
+ export function recordTemplateArt(root) {
92
+ if (templateCaptureActive) artTemplates.add(root);
93
+ }
94
+
95
+ export function templateRequestsArt(root) {
96
+ return artTemplates.has(root);
97
+ }
@@ -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
  }