castle-web-cli 0.4.233 → 0.4.234

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (381) hide show
  1. package/dist/api.d.ts +11 -0
  2. package/dist/api.js +43 -0
  3. package/dist/bundle.d.ts +64 -0
  4. package/dist/bundle.js +558 -2
  5. package/dist/castle-host/host.d.ts +17 -2
  6. package/dist/castle-host/host.js +793 -36
  7. package/dist/castleJson.d.ts +20 -1
  8. package/dist/castleJson.js +44 -2
  9. package/dist/check.js +9 -2
  10. package/dist/chunkLoader.d.ts +3 -0
  11. package/dist/chunkLoader.js +111 -0
  12. package/dist/devParty.d.ts +26 -0
  13. package/dist/devParty.js +231 -0
  14. package/dist/devSaveStorage.js +4 -0
  15. package/dist/devSessionStorage.js +3 -1
  16. package/dist/devSocial.d.ts +24 -0
  17. package/dist/devSocial.js +70 -0
  18. package/dist/ide.d.ts +2 -0
  19. package/dist/ide.js +119 -15
  20. package/dist/index.js +8 -2
  21. package/dist/init.js +1 -1
  22. package/dist/save-deck.d.ts +20 -1
  23. package/dist/save-deck.js +141 -5
  24. package/dist/serve.js +29 -11
  25. package/dist/shell/assets/{index-BjOxR-lW.js → index-DulbYIJm.js} +97 -97
  26. package/dist/shell/index.html +1 -1
  27. package/dist/vitePlugins.d.ts +2 -1
  28. package/dist/vitePlugins.js +13 -0
  29. package/kits/base/castle.json +1 -1
  30. package/kits/base/sdk/README.md +260 -3
  31. package/kits/base/sdk/castle.d.ts +7 -3
  32. package/kits/base/sdk/castle.js +2 -0
  33. package/kits/base/sdk/commands.d.ts +162 -1
  34. package/kits/base/sdk/commands.js +3 -0
  35. package/kits/base/sdk/display.d.ts +3 -0
  36. package/kits/base/sdk/display.js +9 -3
  37. package/kits/base/sdk/hub.d.ts +33 -6
  38. package/kits/base/sdk/hub.js +50 -4
  39. package/kits/base/sdk/multiplayer.d.ts +7 -1
  40. package/kits/base/sdk/multiplayer.js +140 -40
  41. package/kits/base/sdk/multiplayerProtocol.d.ts +2 -0
  42. package/kits/base/sdk/party.d.ts +23 -0
  43. package/kits/base/sdk/party.js +91 -0
  44. package/kits/base/sdk/reconnectBudget.d.ts +23 -0
  45. package/kits/base/sdk/reconnectBudget.js +96 -0
  46. package/kits/base/sdk/save.d.ts +38 -1
  47. package/kits/base/sdk/save.js +79 -6
  48. package/kits/base/sdk/server/hub.d.ts +31 -1
  49. package/kits/base/sdk/server/hub.js +50 -3
  50. package/kits/base/sdk/server/platformHandle.d.ts +13 -1
  51. package/kits/base/sdk/server/storage.d.ts +4 -0
  52. package/kits/base/sdk/server/storage.js +19 -3
  53. package/kits/base/sdk/server/wrapper.d.ts +7 -1
  54. package/kits/base/sdk/server/wrapper.js +10 -1
  55. package/kits/base/sdk/social.d.ts +9 -0
  56. package/kits/base/sdk/social.js +5 -0
  57. package/kits/hub-game/CLAUDE.md +123 -3
  58. package/kits/hub-game/README.md +63 -0
  59. package/kits/hub-game/castle.json +5 -5
  60. package/kits/hub-game/code/client/act.js +312 -0
  61. package/kits/hub-game/code/client/actionLayout.js +147 -0
  62. package/kits/hub-game/code/client/actionOverflow.js +556 -0
  63. package/kits/hub-game/code/client/arrivalCamera.js +50 -0
  64. package/kits/hub-game/code/client/askSlot.js +117 -0
  65. package/kits/hub-game/code/client/avatar.js +4 -2
  66. package/kits/hub-game/code/client/avatarShare.js +2 -0
  67. package/kits/hub-game/code/client/backVisibility.js +13 -0
  68. package/kits/hub-game/code/client/ballot.js +15 -10
  69. package/kits/hub-game/code/client/build.js +16 -0
  70. package/kits/hub-game/code/client/chat.js +41 -5
  71. package/kits/hub-game/code/client/chatModeration.js +5 -0
  72. package/kits/hub-game/code/client/chrome.js +1148 -258
  73. package/kits/hub-game/code/client/crowdNames.js +241 -0
  74. package/kits/hub-game/code/client/decor.js +10 -4
  75. package/kits/hub-game/code/client/defaultEnvironment.js +194 -0
  76. package/kits/hub-game/code/client/doorErrors.js +39 -0
  77. package/kits/hub-game/code/client/fall.js +18 -0
  78. package/kits/hub-game/code/client/farAvatars.js +233 -0
  79. package/kits/hub-game/code/client/firstJoin.js +9 -2
  80. package/kits/hub-game/code/client/fpsTelemetry.js +50 -0
  81. package/kits/hub-game/code/client/frameBatch.js +5 -0
  82. package/kits/hub-game/code/client/grab.js +31 -11
  83. package/kits/hub-game/code/client/hookLayer.js +87 -8
  84. package/kits/hub-game/code/client/hudCopy.js +51 -0
  85. package/kits/hub-game/code/client/hudRate.js +20 -0
  86. package/kits/hub-game/code/client/idle.js +14 -2
  87. package/kits/hub-game/code/client/invites.js +231 -0
  88. package/kits/hub-game/code/client/joinError.js +9 -0
  89. package/kits/hub-game/code/client/labelsNear.js +31 -2
  90. package/kits/hub-game/code/client/landscapeLayout.js +17 -0
  91. package/kits/hub-game/code/client/layoutCache.js +264 -0
  92. package/kits/hub-game/code/client/loadTelemetry.js +20 -0
  93. package/kits/hub-game/code/client/loadingCover.js +148 -0
  94. package/kits/hub-game/code/client/loadingEntry.js +8 -0
  95. package/kits/hub-game/code/client/menuRows.js +43 -0
  96. package/kits/hub-game/code/client/modelReady.js +7 -0
  97. package/kits/hub-game/code/client/padCueArrival.js +23 -0
  98. package/kits/hub-game/code/client/padCues.js +112 -0
  99. package/kits/hub-game/code/client/padOccupancy.js +88 -0
  100. package/kits/hub-game/code/client/padReadability.js +26 -0
  101. package/kits/hub-game/code/client/padRings.js +69 -0
  102. package/kits/hub-game/code/client/pushVisit.js +14 -0
  103. package/kits/hub-game/code/client/quality.js +205 -0
  104. package/kits/hub-game/code/client/qualityEntry.js +55 -0
  105. package/kits/hub-game/code/client/safeLayout.js +338 -0
  106. package/kits/hub-game/code/client/safeStyle.js +42 -0
  107. package/kits/hub-game/code/client/say.js +12 -3
  108. package/kits/hub-game/code/client/shot.js +64 -10
  109. package/kits/hub-game/code/client/shotFit.js +56 -0
  110. package/kits/hub-game/code/client/signIn.js +28 -0
  111. package/kits/hub-game/code/client/state.js +53 -0
  112. package/kits/hub-game/code/client/talk.js +209 -45
  113. package/kits/hub-game/code/client/tiers.js +68 -66
  114. package/kits/hub-game/code/client/together.js +7 -2
  115. package/kits/hub-game/code/client/weakestLookBake.js +92 -0
  116. package/kits/hub-game/code/client/weakestTier.js +295 -0
  117. package/kits/hub-game/code/client/worldLabels.js +241 -0
  118. package/kits/hub-game/code/client/yours.js +10 -9
  119. package/kits/hub-game/code/npcDisplayText.js +55 -0
  120. package/kits/hub-game/code/server/act.js +124 -0
  121. package/kits/hub-game/code/server/actions.js +6 -1
  122. package/kits/hub-game/code/server/actors.js +2 -1
  123. package/kits/hub-game/code/server/analytics.js +83 -0
  124. package/kits/hub-game/code/server/anonymousEntry.js +49 -0
  125. package/kits/hub-game/code/server/arrivalPose.js +36 -0
  126. package/kits/hub-game/code/server/companion.js +28 -3
  127. package/kits/hub-game/code/server/doorAnalytics.js +52 -0
  128. package/kits/hub-game/code/server/earned.js +22 -5
  129. package/kits/hub-game/code/server/frameBatch.js +183 -0
  130. package/kits/hub-game/code/server/friendsAmong.js +49 -9
  131. package/kits/hub-game/code/server/history.js +2 -0
  132. package/kits/hub-game/code/server/hub.js +1306 -95
  133. package/kits/hub-game/code/server/idle.js +30 -1
  134. package/kits/hub-game/code/server/index.js +26 -4
  135. package/kits/hub-game/code/server/invites.js +19 -0
  136. package/kits/hub-game/code/server/labels.js +9 -1
  137. package/kits/hub-game/code/server/loadAbandon.js +106 -0
  138. package/kits/hub-game/code/server/manifest.js +211 -3
  139. package/kits/hub-game/code/server/menu.js +31 -3
  140. package/kits/hub-game/code/server/npcs.js +226 -64
  141. package/kits/hub-game/code/server/observe.js +408 -0
  142. package/kits/hub-game/code/server/padOccupancy.js +85 -0
  143. package/kits/hub-game/code/server/players.js +9 -1
  144. package/kits/hub-game/code/server/resumePose.js +152 -0
  145. package/kits/hub-game/code/server/say.js +1 -1
  146. package/kits/hub-game/code/server/standing.js +4 -5
  147. package/kits/hub-game/code/server/storageLimit.js +187 -0
  148. package/kits/hub-game/code/server/vis.js +67 -5
  149. package/kits/hub-game/code/shared/act.js +35 -0
  150. package/kits/hub-game/code/shared/danceIdle.js +28 -0
  151. package/kits/hub-game/code/shared/loadStages.js +12 -0
  152. package/kits/hub-game/code/shared/quality.js +74 -0
  153. package/kits/hub-game/code/shared/say.js +2 -0
  154. package/kits/hub-game/code/shared/shot.js +35 -1
  155. package/kits/hub-game/code/systems/hub.js +970 -169
  156. package/kits/hub-game/docs/analytics.md +279 -0
  157. package/kits/hub-game/docs/contract.md +1257 -42
  158. package/kits/hub-game/docs/home-pieces.md +9 -2
  159. package/kits/hub-game/docs/observed-progress.md +252 -0
  160. package/kits/hub-game/main.jsx +2 -0
  161. package/kits/hub-game/package-lock.json +10 -3
  162. package/kits/hub-game/package.json +6 -3
  163. package/kits/hub-game/play/player.js +142 -0
  164. package/kits/hub-game/play/registry.js +47 -0
  165. package/kits/hub-game/play.jsx +37 -0
  166. package/kits/hub-game/scripts/check.mjs +39 -5
  167. package/kits/hub-game/scripts/companion-follower-wire.json +1 -1
  168. package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +11 -0
  169. package/kits/hub-game/scripts/fixtures/decor-keyless.json +5 -5
  170. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +3 -0
  171. package/kits/hub-game/scripts/fixtures/fake-dom.mjs +19 -3
  172. package/kits/hub-game/scripts/fixtures/interest-legacy.json +3 -3
  173. package/kits/hub-game/scripts/fixtures/vis-shared-wire.json +1 -1
  174. package/kits/hub-game/scripts/pose-storage-fixture.mjs +46 -0
  175. package/kits/hub-game/scripts/test-act-client.mjs +186 -0
  176. package/kits/hub-game/scripts/test-act.mjs +171 -0
  177. package/kits/hub-game/scripts/test-action-layout.mjs +80 -0
  178. package/kits/hub-game/scripts/test-action-observers.mjs +46 -0
  179. package/kits/hub-game/scripts/test-actions-client.mjs +367 -2
  180. package/kits/hub-game/scripts/test-actors.mjs +20 -7
  181. package/kits/hub-game/scripts/test-analytics.mjs +76 -0
  182. package/kits/hub-game/scripts/test-anonymous-entry.mjs +28 -0
  183. package/kits/hub-game/scripts/test-arrival-pose-server.mjs +196 -0
  184. package/kits/hub-game/scripts/test-arrival-pose.mjs +24 -0
  185. package/kits/hub-game/scripts/test-ask-slot.mjs +85 -0
  186. package/kits/hub-game/scripts/test-avatar-wire.mjs +49 -10
  187. package/kits/hub-game/scripts/test-avatar.mjs +44 -0
  188. package/kits/hub-game/scripts/test-back-visibility.mjs +82 -0
  189. package/kits/hub-game/scripts/test-ballot.mjs +11 -4
  190. package/kits/hub-game/scripts/test-ban-join.mjs +121 -13
  191. package/kits/hub-game/scripts/test-build.mjs +20 -2
  192. package/kits/hub-game/scripts/test-chat.mjs +206 -5
  193. package/kits/hub-game/scripts/test-companion-chat.mjs +20 -2
  194. package/kits/hub-game/scripts/test-control-layout-dom.mjs +120 -0
  195. package/kits/hub-game/scripts/test-crowd-names.mjs +205 -0
  196. package/kits/hub-game/scripts/test-decor-client.mjs +45 -4
  197. package/kits/hub-game/scripts/test-decor.mjs +7 -0
  198. package/kits/hub-game/scripts/test-default-environment-root.mjs +95 -0
  199. package/kits/hub-game/scripts/test-default-environment.mjs +267 -0
  200. package/kits/hub-game/scripts/test-door-analytics.mjs +58 -0
  201. package/kits/hub-game/scripts/test-door-jump.mjs +100 -0
  202. package/kits/hub-game/scripts/test-earned.mjs +33 -3
  203. package/kits/hub-game/scripts/test-far-avatars.mjs +340 -0
  204. package/kits/hub-game/scripts/test-fps-telemetry.mjs +112 -0
  205. package/kits/hub-game/scripts/test-frame-batch.mjs +252 -0
  206. package/kits/hub-game/scripts/test-fresh-friends.mjs +118 -0
  207. package/kits/hub-game/scripts/test-grab-orbit.mjs +47 -4
  208. package/kits/hub-game/scripts/test-high-only.mjs +170 -0
  209. package/kits/hub-game/scripts/test-hub-ops.mjs +321 -2
  210. package/kits/hub-game/scripts/test-hub-trip.mjs +879 -11
  211. package/kits/hub-game/scripts/test-hud-clear.mjs +162 -59
  212. package/kits/hub-game/scripts/test-hud-defects-dom.mjs +100 -0
  213. package/kits/hub-game/scripts/test-hud-rate.mjs +224 -0
  214. package/kits/hub-game/scripts/test-hud-safe-visibility-dom.mjs +83 -0
  215. package/kits/hub-game/scripts/test-idle.mjs +66 -0
  216. package/kits/hub-game/scripts/test-interest-cells.mjs +20 -0
  217. package/kits/hub-game/scripts/test-interest.mjs +15 -0
  218. package/kits/hub-game/scripts/test-invites-client.mjs +430 -0
  219. package/kits/hub-game/scripts/test-invites.mjs +109 -0
  220. package/kits/hub-game/scripts/test-labels.mjs +71 -3
  221. package/kits/hub-game/scripts/test-landscape-layout.mjs +194 -0
  222. package/kits/hub-game/scripts/test-list-scroll-dom.mjs +49 -0
  223. package/kits/hub-game/scripts/test-load-abandon.mjs +246 -0
  224. package/kits/hub-game/scripts/test-loading-cover.mjs +162 -0
  225. package/kits/hub-game/scripts/test-manifest.mjs +265 -0
  226. package/kits/hub-game/scripts/test-menu-client.mjs +105 -0
  227. package/kits/hub-game/scripts/test-menu.mjs +23 -0
  228. package/kits/hub-game/scripts/test-npcs.mjs +819 -10
  229. package/kits/hub-game/scripts/test-observed.mjs +745 -0
  230. package/kits/hub-game/scripts/test-pad-cues.mjs +304 -0
  231. package/kits/hub-game/scripts/test-pad-occupancy.mjs +177 -0
  232. package/kits/hub-game/scripts/test-picker.mjs +234 -7
  233. package/kits/hub-game/scripts/test-placement-cache.mjs +690 -0
  234. package/kits/hub-game/scripts/test-progress-reset.mjs +559 -0
  235. package/kits/hub-game/scripts/test-push-visit.mjs +26 -0
  236. package/kits/hub-game/scripts/test-quality.mjs +385 -0
  237. package/kits/hub-game/scripts/test-rehello.mjs +699 -5
  238. package/kits/hub-game/scripts/test-resume-action-order.mjs +598 -0
  239. package/kits/hub-game/scripts/test-resume-held.mjs +239 -0
  240. package/kits/hub-game/scripts/test-resume-pose.mjs +142 -0
  241. package/kits/hub-game/scripts/test-safe-events-dom.mjs +116 -0
  242. package/kits/hub-game/scripts/test-safe-layout.mjs +330 -0
  243. package/kits/hub-game/scripts/test-say.mjs +1 -1
  244. package/kits/hub-game/scripts/test-shot.mjs +145 -0
  245. package/kits/hub-game/scripts/test-signin-client.mjs +45 -0
  246. package/kits/hub-game/scripts/test-soundscape.mjs +22 -17
  247. package/kits/hub-game/scripts/test-standing.mjs +35 -2
  248. package/kits/hub-game/scripts/test-storage-limit.mjs +333 -0
  249. package/kits/hub-game/scripts/test-stuck.mjs +5 -4
  250. package/kits/hub-game/scripts/test-talk-overlay-dom.mjs +130 -0
  251. package/kits/hub-game/scripts/test-tiers-render.mjs +86 -13
  252. package/kits/hub-game/scripts/test-tiers.mjs +7 -8
  253. package/kits/hub-game/scripts/test-vis.mjs +433 -6
  254. package/kits/hub-game/scripts/test-weakest-tier.mjs +924 -0
  255. package/kits/hub-game/scripts/test-world-labels.mjs +367 -0
  256. package/kits/hub-game/scripts/test-yours-chrome.mjs +50 -6
  257. package/kits/hub-game/scripts/test-yours.mjs +39 -8
  258. package/kits/multiplayer-3d/castle.json +5 -5
  259. package/kits/multiplayer-3d/code/client/joinFailure.js +27 -0
  260. package/kits/multiplayer-3d/code/client/resumeGate.js +139 -0
  261. package/kits/multiplayer-3d/code/systems/multiplayer.js +369 -30
  262. package/kits/multiplayer-3d/package-lock.json +8 -1
  263. package/kits/multiplayer-3d/package.json +2 -1
  264. package/kits/multiplayer-3d/scripts/test-join-watchdog.mjs +436 -0
  265. package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +624 -0
  266. package/kits/physics-2d/CLAUDE.md +10 -1
  267. package/kits/physics-2d/castle.json +2 -2
  268. package/kits/physics-2d/engine/frozenActors.js +233 -0
  269. package/kits/physics-2d/engine/scene.js +87 -5
  270. package/kits/physics-2d/eslint.config.js +1 -1
  271. package/kits/physics-2d/play/behaviors/AnalogStick.js +198 -0
  272. package/kits/physics-2d/play/behaviors/Camera.js +40 -0
  273. package/kits/physics-2d/play/behaviors/Collider.js +122 -0
  274. package/kits/physics-2d/play/behaviors/Draggable.js +115 -0
  275. package/kits/physics-2d/play/behaviors/Goal.js +46 -0
  276. package/kits/physics-2d/play/behaviors/Joints.js +126 -0
  277. package/kits/physics-2d/play/behaviors/Layout.js +71 -0
  278. package/kits/physics-2d/play/behaviors/RigidBody.js +57 -0
  279. package/kits/physics-2d/play/behaviors/Slingshot.js +142 -0
  280. package/kits/physics-2d/play/behaviors/SoundPlayer.js +263 -0
  281. package/kits/physics-2d/play/behaviors/Sprite.js +406 -0
  282. package/kits/physics-2d/play/behaviors/Style.js +209 -0
  283. package/kits/physics-2d/play/behaviors/Text.js +85 -0
  284. package/kits/physics-2d/play/behaviors/Video.js +93 -0
  285. package/kits/physics-3d/CLAUDE.md +25 -1651
  286. package/kits/physics-3d/behaviors/Body.jsx +3 -0
  287. package/kits/physics-3d/behaviors/Model.jsx +3 -0
  288. package/kits/physics-3d/behaviors/Player.jsx +35 -18
  289. package/kits/physics-3d/behaviors/Shape.jsx +3 -0
  290. package/kits/physics-3d/behaviors/Solid.jsx +3 -0
  291. package/kits/physics-3d/behaviors/Transform.jsx +3 -0
  292. package/kits/physics-3d/castle.json +3 -3
  293. package/kits/physics-3d/docs/engine-camera.md +542 -0
  294. package/kits/physics-3d/docs/engine-frame-cap.md +136 -0
  295. package/kits/physics-3d/docs/engine-load.md +149 -0
  296. package/kits/physics-3d/docs/engine-look.md +114 -0
  297. package/kits/physics-3d/docs/engine-shadows.md +372 -0
  298. package/kits/physics-3d/docs/engine-skip-work.md +187 -0
  299. package/kits/physics-3d/docs/engine-sky.md +198 -0
  300. package/kits/physics-3d/docs/engine-static-actors.md +226 -0
  301. package/kits/physics-3d/docs/engine-view.md +37 -0
  302. package/kits/physics-3d/docs/pxmodel-format.md +1 -1
  303. package/kits/physics-3d/engine3d/PlayOnly3D.jsx +5 -1
  304. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +19 -333
  305. package/kits/physics-3d/engine3d/actornode.js +1 -0
  306. package/kits/physics-3d/engine3d/branches.js +3 -13
  307. package/kits/physics-3d/engine3d/cage.js +2 -7
  308. package/kits/physics-3d/engine3d/cageops.js +2 -17
  309. package/kits/physics-3d/engine3d/dataBehaviors.js +12 -0
  310. package/kits/physics-3d/engine3d/framecap.js +4 -1
  311. package/kits/physics-3d/engine3d/frozenphysics.js +140 -0
  312. package/kits/physics-3d/engine3d/frozenstatics.js +273 -0
  313. package/kits/physics-3d/engine3d/gait.js +8 -0
  314. package/kits/physics-3d/engine3d/initialModelFiles.js +18 -0
  315. package/kits/physics-3d/engine3d/look.js +7 -0
  316. package/kits/physics-3d/engine3d/modelFiles.js +3 -17
  317. package/kits/physics-3d/engine3d/modelMath.js +49 -0
  318. package/kits/physics-3d/engine3d/modelready.js +16 -0
  319. package/kits/physics-3d/engine3d/motion.js +3 -3
  320. package/kits/physics-3d/engine3d/nearshadows.js +77 -10
  321. package/kits/physics-3d/engine3d/orbitinput.js +59 -25
  322. package/kits/physics-3d/engine3d/partgeometry.js +1 -16
  323. package/kits/physics-3d/engine3d/paths.js +1 -9
  324. package/kits/physics-3d/engine3d/playTimings.js +50 -0
  325. package/kits/physics-3d/engine3d/playerRun.js +372 -0
  326. package/kits/physics-3d/engine3d/pxmodel.js +3 -3
  327. package/kits/physics-3d/engine3d/rapier.js +27 -0
  328. package/kits/physics-3d/engine3d/scatter.js +1 -11
  329. package/kits/physics-3d/engine3d/shadowfade.js +23 -15
  330. package/kits/physics-3d/engine3d/sky.js +1 -1
  331. package/kits/physics-3d/engine3d/squarefirst.js +177 -0
  332. package/kits/physics-3d/engine3d/stillshadows.js +399 -0
  333. package/kits/physics-3d/engine3d/sweep.js +1 -25
  334. package/kits/physics-3d/engine3d/world3d.js +468 -18
  335. package/kits/physics-3d/eslint.config.js +2 -1
  336. package/kits/physics-3d/main.jsx +6 -3
  337. package/kits/physics-3d/package-lock.json +7 -0
  338. package/kits/physics-3d/package.json +5 -1
  339. package/kits/physics-3d/play/behaviors/Body.js +31 -0
  340. package/kits/physics-3d/play/behaviors/Door.js +37 -0
  341. package/kits/physics-3d/play/behaviors/Lookable.js +16 -0
  342. package/kits/physics-3d/play/behaviors/Model.js +23 -0
  343. package/kits/physics-3d/play/behaviors/Pickup.js +46 -0
  344. package/kits/physics-3d/play/behaviors/Player.js +1204 -0
  345. package/kits/physics-3d/play/behaviors/Shape.js +47 -0
  346. package/kits/physics-3d/play/behaviors/Solid.js +16 -0
  347. package/kits/physics-3d/play/behaviors/Transform.js +29 -0
  348. package/kits/physics-3d/pnpm-lock.yaml +8 -0
  349. package/kits/physics-3d/scripts/bench-shadow-fade.mjs +37 -0
  350. package/kits/physics-3d/scripts/build-rapier-gz.mjs +56 -0
  351. package/kits/physics-3d/scripts/frozen-statics-fixture.mjs +141 -0
  352. package/kits/physics-3d/scripts/test-camera-follow.mjs +5 -1
  353. package/kits/physics-3d/scripts/test-camera-orbit.mjs +52 -4
  354. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +1 -1
  355. package/kits/physics-3d/scripts/test-empty-gait-hints.mjs +89 -0
  356. package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +6 -3
  357. package/kits/physics-3d/scripts/test-frame-cap.mjs +1 -1
  358. package/kits/physics-3d/scripts/test-frozen-nested.mjs +49 -0
  359. package/kits/physics-3d/scripts/test-frozen-statics-legacy-physics2d.mjs +123 -0
  360. package/kits/physics-3d/scripts/test-frozen-statics.mjs +434 -0
  361. package/kits/physics-3d/scripts/test-look-bake.mjs +1 -1
  362. package/kits/physics-3d/scripts/test-near-shadows.mjs +2 -2
  363. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +88 -7
  364. package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +40 -3
  365. package/kits/physics-3d/scripts/test-orbit-shot.mjs +75 -1
  366. package/kits/physics-3d/scripts/test-rapier-gz.mjs +106 -0
  367. package/kits/physics-3d/scripts/test-sky.mjs +1 -1
  368. package/kits/physics-3d/scripts/test-square-first.mjs +921 -0
  369. package/kits/physics-3d/scripts/test-static-actors.mjs +3 -1
  370. package/kits/physics-3d/scripts/test-static-physics.mjs +4 -1
  371. package/kits/physics-3d/scripts/test-static-scenery.mjs +5 -2
  372. package/kits/physics-3d/scripts/test-steady-hover.mjs +5 -2
  373. package/kits/physics-3d/scripts/test-still-shadows.mjs +477 -0
  374. package/kits/physics-3d/systems/physics3d.js +37 -4
  375. package/kits/real-time/castle.json +2 -2
  376. package/kits/real-time/code/client/connection.js +33 -10
  377. package/kits/real-time/code/client/gameHooks.js +2 -0
  378. package/kits/real-time/code/client/joinOverlay.js +9 -4
  379. package/kits/real-time/code/server/session.js +6 -4
  380. package/kits/real-time/package-lock.json +1 -1
  381. package/package.json +2 -2
@@ -659,6 +659,7 @@ const physics = await (await import('./test-static-physics.mjs')).run();
659
659
  const shadows = await (await import('./test-near-shadows.mjs')).run();
660
660
  const view = await (await import('./test-orbit-view.mjs')).run();
661
661
  const fade = await (await import('./test-orbit-shadow-fade.mjs')).run();
662
+ const stillShadows = await (await import('./test-still-shadows.mjs')).run();
662
663
  const camera = await (await import('./test-camera-follow.mjs')).run();
663
664
  const hover = await import('./test-steady-hover.mjs');
664
665
  const steady = hover.summary(await hover.run());
@@ -671,4 +672,5 @@ const frameCap = (await import('./test-frame-cap.mjs')).run();
671
672
  const bobTest = await import('./test-frame-cap-bob.mjs');
672
673
  const bob = bobTest.summary(await bobTest.run());
673
674
  readsAreRecorded();
674
- console.log(`static actors: ${trees.frames} tree frames equal a plain Group's (${trees.skipped} skipped), ${values.yes + values.no} value checks, ${passes} pass scenarios end as without the key, ${physics} physics scenarios keep nothing past their world, ${shadows} near-shadow scenarios leave the sun as it was, ${view} orbit-lens scenarios (touched under the key only), ${fade} orbit shadow-fade scenarios (materials untouched without both keys), ${camera.checks} follow-camera checks, ${steady}, ${orbit}, ${dropped}, ${scenery}, ${sky} sky scenarios (nothing on a world without the key), ${frameCap} frame-cap cases run main's frames without the key, ${bob}`);
675
+ const emptyGait = (await import('./test-empty-gait-hints.mjs')).run();
676
+ console.log(`static actors: ${trees.frames} tree frames equal a plain Group's (${trees.skipped} skipped), ${values.yes + values.no} value checks, ${passes} pass scenarios end as without the key, ${physics} physics scenarios keep nothing past their world, ${shadows} near-shadow scenarios leave the sun as it was, ${view} orbit-lens scenarios (touched under the key only), ${fade} orbit shadow-fade scenarios (materials untouched without both keys), ${stillShadows} still-shadow scenarios, ${camera.checks} follow-camera checks, ${steady}, ${orbit}, ${dropped}, ${scenery}, ${sky} sky scenarios (nothing on a world without the key), ${frameCap} frame-cap cases run main's frames without the key, ${bob}, ${emptyGait}`);
@@ -32,8 +32,11 @@ const hooks = `
32
32
  import { existsSync } from 'node:fs';
33
33
  import { fileURLToPath } from 'node:url';
34
34
  export async function resolve(specifier, context, next) {
35
+ const isRapier = specifier === '@dimforge/rapier3d-compat' ||
36
+ ((specifier.startsWith('.') || specifier.startsWith('file:')) &&
37
+ new URL(specifier, context.parentURL).href.endsWith('/kits/physics-3d/engine3d/rapier.js'));
35
38
  const parent = context.parentURL ?? '';
36
- if (specifier === '@dimforge/rapier3d-compat') {
39
+ if (isRapier) {
37
40
  return { url: 'data:text/javascript,' + encodeURIComponent(${JSON.stringify(stub)}), shortCircuit: true };
38
41
  }
39
42
  if (specifier.startsWith('@imports/castle.physics-2d/')) {
@@ -1,5 +1,5 @@
1
1
  // `"engine": { "staticActors": true }` (engine3d/world3d.js and actornode.js,
2
- // systems/physics3d.js, physics-2d engine/scene.js; CLAUDE.md has the terms),
2
+ // systems/physics3d.js, physics-2d engine/scene.js; docs/engine-static-actors.md has the terms),
3
3
  // on the real SceneRuntime, the real physics system over a stand-in rapier
4
4
  // (rapier itself is not installed where this runs), the real `syncActors` and
5
5
  // `renderWorld`, and real models.
@@ -132,9 +132,12 @@ const hooks = `
132
132
  const stubs = ${JSON.stringify(stubs)};
133
133
  const stub = (name) => ({ url: 'data:text/javascript,' + encodeURIComponent(stubs[name]), shortCircuit: true });
134
134
  export async function resolve(specifier, context, next) {
135
+ const isRapier = specifier === '@dimforge/rapier3d-compat' ||
136
+ ((specifier.startsWith('.') || specifier.startsWith('file:')) &&
137
+ new URL(specifier, context.parentURL).href.endsWith('/kits/physics-3d/engine3d/rapier.js'));
135
138
  const parent = context.parentURL ?? '';
136
139
  if (specifier === 'castle-web-sdk') return stub(specifier);
137
- if (specifier === '@dimforge/rapier3d-compat' && parent.endsWith('?still')) return stub('rapier');
140
+ if (isRapier && parent.endsWith('?still')) return stub('rapier');
138
141
  if (/\\?still$/.test(specifier)) return { url: new URL(specifier, parent).href, shortCircuit: true };
139
142
  const kit = /^@imports\\/castle\\.([a-z0-9-]+)\\/(.*)$/.exec(specifier);
140
143
  if (kit) specifier = parent.replace(/\\/kits\\/.*/, '/kits/' + kit[1] + '/') + kit[2];
@@ -109,9 +109,12 @@ const hooks = `
109
109
  const fake = 'data:text/javascript,' + encodeURIComponent(${JSON.stringify(fakeRapier)});
110
110
  const real = ${JSON.stringify(realRapier)};
111
111
  export async function resolve(specifier, context, next) {
112
+ const isRapier = specifier === '@dimforge/rapier3d-compat' ||
113
+ ((specifier.startsWith('.') || specifier.startsWith('file:')) &&
114
+ new URL(specifier, context.parentURL).href.endsWith('/kits/physics-3d/engine3d/rapier.js'));
112
115
  const parent = context.parentURL ?? '';
113
- if (specifier === '@dimforge/rapier3d-compat' && parent.endsWith('?steady-fake')) return { url: fake, shortCircuit: true };
114
- if (specifier === '@dimforge/rapier3d-compat' && parent.endsWith('?steady-real')) return { url: real, shortCircuit: true };
116
+ if (isRapier && parent.endsWith('?steady-fake')) return { url: fake, shortCircuit: true };
117
+ if (isRapier && parent.endsWith('?steady-real')) return { url: real, shortCircuit: true };
115
118
  // This file's own copies of the physics system, one per rapier; settled
116
119
  // here so no other test's hooks rewrite the address.
117
120
  if (/\\?steady-(fake|real)$/.test(specifier)) return { url: new URL(specifier, parent).href, shortCircuit: true };
@@ -0,0 +1,477 @@
1
+ // Real r180 WebGLRenderer, shadow pass, render lists, and shader compilation
2
+ // over the existing fake WebGL2 context. A tiny software depth target also
3
+ // checks copy/clear ordering, overlapping casters, and departed movers.
4
+ import assert from 'node:assert/strict';
5
+ import * as THREE from 'three';
6
+ import { makeWorld, makeStuff, runtime, frames } from './test-orbit-shadow-fade.mjs';
7
+ import { ActorNode, freezeWhenUnchanged, isFrozen } from '../engine3d/actornode.js';
8
+ import { StillKeeper } from '../../physics-2d/engine/stillClock.js';
9
+ import { STABLE_FRAMES } from '../engine3d/stillshadows.js';
10
+ const { renderWorld, disposeWorld } = await import('../engine3d/world3d.js');
11
+ const { dropNearShadows: dropNearShadowsForTest } = await import('../engine3d/nearshadows.js');
12
+ const WARMUP = STABLE_FRAMES + 1; // Includes near shadows' first plain frame.
13
+
14
+ function setup(options = {}) {
15
+ const { orbit = false } = options;
16
+ const key = Object.hasOwn(options, 'key') ? options.key : true;
17
+ const world = makeWorld(makeStuff());
18
+ const run = runtime(world, { orbit, distance: 40 });
19
+ if (key !== undefined) run.data.engine.shadows.cacheStill = key;
20
+ run.stillVersion = 1;
21
+ run.keepsStaticActors = true;
22
+ let clock = 1;
23
+ Object.assign(world.skipping, { on: true, epoch: 1, clock: () => clock, clockAt: clock });
24
+ world.stillKeeper = new StillKeeper();
25
+ const mesh = world.scene.getObjectByName('standard');
26
+ const mover = world.scene.getObjectByName('physical');
27
+ const node = new ActorNode(world.skipping);
28
+ world.scene.remove(mesh);
29
+ node.add(mesh);
30
+ world.scene.add(node);
31
+ const freeze = () => {
32
+ world.stillKeeper.adopted = { version: run.stillVersion };
33
+ world.skipping.clockAt = clock;
34
+ world.scene.updateMatrixWorld();
35
+ freezeWhenUnchanged(node);
36
+ world.scene.updateMatrixWorld();
37
+ assert.ok(isFrozen(node));
38
+ };
39
+ freeze();
40
+ const events = [];
41
+ const pixels = new Map();
42
+ const direct = world.renderer.renderBufferDirect;
43
+ const clear = world.renderer.clear;
44
+ world.renderer.clear = function (...args) {
45
+ const target = this.getRenderTarget();
46
+ pixels.set(target, [1, 1]);
47
+ events.push({ clear: target });
48
+ return clear.apply(this, args);
49
+ };
50
+ mesh.userData.testPixel = [0, 0.3];
51
+ mover.userData.testPixel = [0, 0.2];
52
+ world.renderer.renderBufferDirect = function (camera, scene, geometry, material, object, group) {
53
+ const target = this.getRenderTarget();
54
+ const copy = material.uniforms?.cachedDepth !== undefined;
55
+ events.push({ target, object, material, copy });
56
+ if (copy) pixels.set(target, [...pixels.get(world.nearShadows.shadow.stillCache.shadow.map)]);
57
+ if (material.isMeshDepthMaterial && object.userData.testPixel) {
58
+ const [pixel, depth] = object.userData.testPixel;
59
+ const image = pixels.get(target);
60
+ image[pixel] = Math.min(image[pixel], depth);
61
+ }
62
+ return direct.call(this, camera, scene, geometry, material, object, group);
63
+ };
64
+ const step = (count = 1) => {
65
+ for (let i = 0; i < count; i++) {
66
+ events.length = 0;
67
+ frames(world, run, 1);
68
+ }
69
+ };
70
+ const touch = () => { clock += 1; run.stillVersion += 1; };
71
+ return { world, run, mesh, mover, node, freeze, step, touch, events, pixels };
72
+ }
73
+
74
+ const cacheOf = side => side.world.nearShadows?.shadow?.stillCache;
75
+ const shadowDraws = side => side.events.filter(event => event.material?.isMeshDepthMaterial);
76
+ const ownState = sun => [sun.shadow, sun.shadow.camera.matrixWorld.clone(), sun.shadow.matrix.clone(), sun.target.matrixWorld.clone()];
77
+
78
+ const scenarios = {
79
+ 'three consecutive matching frames qualify; misses draw only the ordinary pass'() {
80
+ const side = setup();
81
+ side.step();
82
+ for (let frame = 1; frame <= STABLE_FRAMES; frame++) {
83
+ side.step();
84
+ const cache = cacheOf(side);
85
+ assert.equal(cache.valid, frame === STABLE_FRAMES);
86
+ assert.equal(side.events.filter(draw => draw.copy).length, frame === STABLE_FRAMES ? 1 : 0);
87
+ assert.equal(shadowDraws(side).filter(draw => draw.object === side.mesh).length, 1);
88
+ assert.equal(shadowDraws(side).filter(draw => draw.object === side.mover).length, 1);
89
+ if (frame < STABLE_FRAMES) assert.equal(cache.shadow.map, null, 'pending frames allocate no still target');
90
+ }
91
+ side.step();
92
+ assert.ok(!shadowDraws(side).some(draw => draw.object === side.mesh));
93
+ assert.equal(side.events.filter(draw => draw.copy).length, 1);
94
+ },
95
+
96
+ 'layer 1 uploads the copy geometry and keeps still shadows on a hit'() {
97
+ const side = setup();
98
+ side.world.camera.layers.set(1);
99
+ side.world.scene.traverse(object => object.layers.set(1));
100
+ side.step(WARMUP);
101
+ const cache = cacheOf(side);
102
+ assert.ok(cache.valid);
103
+ assert.ok(cache.triangle.layers.test(side.world.camera.layers));
104
+ assert.equal(side.world.renderer.info.memory.geometries, 3, 'the camera walk uploaded the copy geometry');
105
+ side.step();
106
+ assert.equal(side.events.filter(draw => draw.copy).length, 1);
107
+ assert.ok(!shadowDraws(side).some(draw => draw.object === side.mesh));
108
+ assert.deepEqual(side.pixels.get(side.world.nearShadows.shadow.map), [0.2, 1]);
109
+ },
110
+
111
+ 'nested renders with another camera or scene bypass the primary cache'() {
112
+ for (const kind of ['camera', 'scene']) {
113
+ const side = setup();
114
+ side.world.scene.children.find(object => object.isDirectionalLight).layers.enableAll();
115
+ let renderScene = side.world.scene;
116
+ let renderCamera = side.world.camera;
117
+ const secondary = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshStandardMaterial());
118
+ secondary.name = 'secondary-only';
119
+ secondary.castShadow = true;
120
+ if (kind === 'camera') {
121
+ secondary.layers.set(1);
122
+ side.world.scene.add(secondary);
123
+ renderCamera = side.world.camera.clone();
124
+ renderCamera.layers.set(1);
125
+ } else {
126
+ renderScene = new THREE.Scene();
127
+ renderScene.add(secondary);
128
+ // Render the same sun, without reparenting or changing the primary
129
+ // scene. This isolates scene identity from camera identity.
130
+ renderScene.children.push(side.world.scene.children.find(object => object.isDirectionalLight));
131
+ }
132
+ side.step(WARMUP);
133
+ const cache = cacheOf(side);
134
+ const primaryKey = cache.was.slice();
135
+ const nested = [];
136
+ const direct = side.world.renderer.renderBufferDirect;
137
+ let inside = false;
138
+ side.world.renderer.renderBufferDirect = function (...args) {
139
+ if (inside) nested.push({ object: args[4], depth: args[3].isMeshDepthMaterial, copy: args[3] === cache.material });
140
+ return direct.apply(this, args);
141
+ };
142
+ let once = true;
143
+ side.world.scene.getObjectByName('ground').onBeforeRender = () => {
144
+ if (!once) return;
145
+ once = false;
146
+ inside = true;
147
+ try { side.world.renderer.render(renderScene, renderCamera); }
148
+ finally { inside = false; }
149
+ };
150
+ side.step();
151
+ assert.ok(nested.some(draw => draw.depth && draw.object === secondary), `${kind}: the actual render's caster draws`);
152
+ assert.ok(!nested.some(draw => draw.copy), `${kind}: no cached primary depths are copied`);
153
+ assert.ok(!nested.some(draw => draw.depth && draw.object === side.mesh), `${kind}: primary-only scenery stays out`);
154
+ assert.deepEqual(cache.was, primaryKey, `${kind}: secondary rendering does not change the primary candidate`);
155
+ assert.ok(cache.valid);
156
+ side.step();
157
+ assert.equal(side.events.filter(draw => draw.copy).length, 1, `${kind}: primary cache still hits`);
158
+ assert.ok(!shadowDraws(side).some(draw => draw.object === side.mesh));
159
+ }
160
+ },
161
+
162
+ 'ten moving frames never add depth draws or copies, from cold and warm caches'() {
163
+ for (const warm of [false, true]) {
164
+ const side = setup();
165
+ const plain = setup({ key: false });
166
+ side.step(warm ? WARMUP : 2);
167
+ plain.step(warm ? WARMUP : 2);
168
+ const cache = cacheOf(side);
169
+ const target = cache.shadow.map;
170
+ const geometries = side.world.renderer.info.memory.geometries;
171
+ const buffers = new Set([cache.now, cache.was]);
172
+ const casters = cache.casters;
173
+ const flags = cache.stillFlags;
174
+ // Guard against allocating a descriptor for every caster in every
175
+ // key computation, as well as replacing the reusable key buffers.
176
+ let collecting = 0;
177
+ let descriptors = 0;
178
+ const collect = cache.collect;
179
+ const descriptor = Object.getOwnPropertyDescriptor;
180
+ cache.collect = function (...args) {
181
+ collecting++;
182
+ try { return collect.apply(this, args); } finally { collecting--; }
183
+ };
184
+ Object.getOwnPropertyDescriptor = function (...args) {
185
+ if (collecting) descriptors++;
186
+ return descriptor(...args);
187
+ };
188
+ let cachedDraws = 0;
189
+ let plainDraws = 0;
190
+ try {
191
+ for (let frame = 0; frame < 10; frame++) {
192
+ side.world.camera.position.x += 1;
193
+ plain.world.camera.position.x += 1;
194
+ side.step();
195
+ plain.step();
196
+ cachedDraws += shadowDraws(side).length;
197
+ plainDraws += shadowDraws(plain).length;
198
+ assert.equal(shadowDraws(side).length, shadowDraws(plain).length, `frame ${frame}: ordinary depth draws only`);
199
+ assert.equal(side.events.filter(draw => draw.copy).length, 0);
200
+ assert.ok(!cache.valid);
201
+ assert.ok(buffers.has(cache.now) && buffers.has(cache.was));
202
+ assert.equal(cache.casters, casters);
203
+ assert.equal(cache.stillFlags, flags);
204
+ }
205
+ } finally {
206
+ Object.getOwnPropertyDescriptor = descriptor;
207
+ }
208
+ assert.equal(descriptors, 0);
209
+ assert.ok(cachedDraws <= plainDraws);
210
+ assert.equal(cache.shadow.map, target, 'moving frames never allocate or rebuild the still target');
211
+ assert.equal(side.world.renderer.info.memory.geometries, geometries);
212
+ }
213
+ },
214
+
215
+ 'still depths reuse; movers update, overlap, and leave no trails'() {
216
+ const side = setup();
217
+ side.step(); // the ordinary warm-up frame
218
+ const sun = side.world.sun;
219
+ const own = ownState(sun);
220
+ side.step(STABLE_FRAMES);
221
+ const near = side.world.nearShadows.shadow;
222
+ const cache = cacheOf(side);
223
+ assert.ok(cache.valid);
224
+ assert.equal(shadowDraws(side).filter(draw => draw.object === side.mesh).length, 1);
225
+ assert.deepEqual(side.pixels.get(near.map), [0.2, 1]);
226
+ for (let i = 0; i < 4; i++) {
227
+ side.step();
228
+ assert.equal(shadowDraws(side).filter(draw => draw.object === side.mesh).length, 0);
229
+ assert.equal(shadowDraws(side).filter(draw => draw.object === side.mover).length, 1);
230
+ assert.equal(side.events.filter(draw => draw.copy).length, 1);
231
+ }
232
+ side.mover.userData.testPixel = [1, 0.4];
233
+ side.mover.position.x += 0.2;
234
+ side.step();
235
+ assert.deepEqual(side.pixels.get(near.map), [0.3, 0.4], 'old mover depth is cleared by the next seed');
236
+ side.mover.userData.testPixel = [0, 0.7];
237
+ side.step();
238
+ assert.deepEqual(side.pixels.get(near.map), [0.3, 1], 'a mover behind scenery loses the hardware depth test');
239
+ assert.deepEqual(ownState(sun), own, 'the sun and its original shadow stay unchanged');
240
+ assert.ok(side.mesh.castShadow && side.mover.castShadow);
241
+ assert.equal(cache.triangle.parent, null);
242
+ assert.equal(cache.material.depthFunc, THREE.AlwaysDepth);
243
+ assert.ok(side.world.gl.sources.some(source => source.includes('gl_FragDepth = texture2D(cachedDepth, vUv).x')));
244
+ assert.equal(side.world.renderer.info.memory.geometries, 3, 'the copy geometry was uploaded by the ordinary object walk');
245
+ },
246
+
247
+ 'subtexel motion reuses; box/light/lens and still-version changes invalidate'() {
248
+ const side = setup();
249
+ side.step(WARMUP);
250
+ const cache = cacheOf(side);
251
+ const original = cache.shadow.map;
252
+ side.world.camera.position.x += 1e-7;
253
+ side.step();
254
+ assert.ok(!shadowDraws(side).some(draw => draw.object === side.mesh));
255
+ for (const change of [
256
+ () => { side.world.camera.position.x += 2; },
257
+ () => { side.world.sun.position.x += 1; },
258
+ () => { side.world.sun.target.position.y += 0.1; side.world.sun.target.updateMatrixWorld(); },
259
+ () => { side.run.stillVersion += 1; side.world.stillKeeper.adopted.version = side.run.stillVersion; },
260
+ () => { side.world.scene.position.x += 1; },
261
+ () => { side.mesh.material.side = THREE.DoubleSide; },
262
+ ]) {
263
+ change();
264
+ side.step();
265
+ assert.ok(shadowDraws(side).some(draw => draw.object === side.mesh), 'a changed key draws the ordinary pass');
266
+ assert.equal(side.events.filter(draw => draw.copy).length, 0, 'a miss never copies or rebuilds');
267
+ assert.equal(cache.valid, false);
268
+ assert.equal(cache.shadow.map, original, 'invalidation reuses storage');
269
+ side.step(STABLE_FRAMES - 1);
270
+ assert.ok(cache.valid && shadowDraws(side).some(draw => draw.object === side.mesh && draw.target === original), 'the settled key rebuilds');
271
+ }
272
+ let freed = 0;
273
+ original.addEventListener('dispose', () => { freed++; });
274
+ side.world.camera.aspect = 2;
275
+ side.world.camera.updateProjectionMatrix();
276
+ side.step();
277
+ assert.equal(freed, 1, 'a resized map is disposed');
278
+ assert.equal(cacheOf(side).shadow.map, null, 'a resize miss draws normally');
279
+ side.freeze();
280
+ side.step(STABLE_FRAMES);
281
+ assert.ok(cacheOf(side).valid);
282
+ assert.notEqual(cacheOf(side).shadow.map, original);
283
+ },
284
+
285
+ 'touch/thaw, animation, spawn, visibility, and caster removal are followed'() {
286
+ const side = setup();
287
+ side.step(WARMUP);
288
+ side.touch();
289
+ side.mesh.position.x += 0.4;
290
+ side.step();
291
+ assert.ok(!isFrozen(side.node));
292
+ assert.ok(shadowDraws(side).some(draw => draw.object === side.mesh && draw.target === side.world.nearShadows.shadow.map));
293
+ side.freeze();
294
+ side.step(STABLE_FRAMES + 1);
295
+ assert.ok(!shadowDraws(side).some(draw => draw.object === side.mesh));
296
+ side.mesh.morphTargetInfluences = [0.5];
297
+ side.step();
298
+ assert.ok(shadowDraws(side).some(draw => draw.object === side.mesh));
299
+ delete side.mesh.morphTargetInfluences;
300
+ side.step(STABLE_FRAMES);
301
+ side.mesh.visible = false;
302
+ side.step();
303
+ assert.equal(side.events.filter(draw => draw.copy).length, 0);
304
+ side.mesh.visible = true;
305
+ side.step(STABLE_FRAMES);
306
+ assert.equal(side.events.filter(draw => draw.copy).length, 1);
307
+ side.mesh.castShadow = false;
308
+ side.step();
309
+ assert.equal(side.events.filter(draw => draw.copy).length, 0);
310
+ side.mesh.castShadow = true;
311
+ const spawned = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshStandardMaterial());
312
+ spawned.castShadow = true;
313
+ spawned.position.z = -2;
314
+ side.world.scene.add(spawned);
315
+ side.step();
316
+ assert.ok(shadowDraws(side).some(draw => draw.object === spawned));
317
+ },
318
+
319
+ 'view-slice selection changes rebuild even with the same snapped box'() {
320
+ const side = setup();
321
+ side.step(WARMUP);
322
+ const near = side.world.nearShadows.shadow;
323
+ const far = new THREE.Mesh(new THREE.SphereGeometry(0.001), new THREE.MeshStandardMaterial());
324
+ far.name = 'outside-slice';
325
+ far.castShadow = true;
326
+ side.node.add(far);
327
+ // Find a point inside the box but outside its narrowed view slice.
328
+ let outside = false;
329
+ for (const x of [-0.9, 0.9]) for (const y of [-0.9, 0.9]) {
330
+ if (outside) continue;
331
+ far.position.set(x, y, 0).unproject(near.camera);
332
+ side.node.computedFrom = null;
333
+ delete side.node.frozenAt;
334
+ side.freeze();
335
+ outside = !near.getFrustum().intersectsObject(far);
336
+ }
337
+ assert.ok(outside);
338
+ side.step(STABLE_FRAMES + 1);
339
+ const matrix = near.matrix.clone();
340
+ assert.ok(!shadowDraws(side).some(draw => draw.object === far));
341
+ far.frustumCulled = false;
342
+ side.step();
343
+ assert.deepEqual(near.matrix, matrix);
344
+ assert.ok(shadowDraws(side).some(draw => draw.object === far), 'the cached draw selection follows three\'s uncullable casters');
345
+ assert.equal(side.events.filter(draw => draw.copy).length, 0, 'the selection miss draws uncached');
346
+ side.step(STABLE_FRAMES - 1);
347
+ assert.ok(shadowDraws(side).some(draw => draw.object === side.mesh && draw.target === cacheOf(side).shadow.map), 'the stable selection rebuilds');
348
+ far.frustumCulled = true;
349
+ side.step();
350
+ assert.ok(!shadowDraws(side).some(draw => draw.object === far));
351
+ assert.ok(shadowDraws(side).some(draw => draw.object === side.mesh));
352
+ },
353
+
354
+ 'frozenStatics nodes cache, and a disposed GPU target rebuilds'() {
355
+ const side = setup();
356
+ side.run.keepsStaticActors = false;
357
+ side.world.stillKeeper.adopted = null;
358
+ side.world.frozenStatics = { runtime: side.run };
359
+ side.node.frozenStatic = true;
360
+ side.step(WARMUP);
361
+ const cache = cacheOf(side);
362
+ assert.ok(cache.valid);
363
+ side.step();
364
+ assert.ok(!shadowDraws(side).some(draw => draw.object === side.mesh));
365
+ cache.shadow.map.dispose(); // Same lost renderer properties as a context restore.
366
+ side.step();
367
+ assert.equal(side.events.filter(draw => draw.copy).length, 0);
368
+ assert.equal(cache.valid, false);
369
+ side.step(STABLE_FRAMES - 1);
370
+ assert.ok(cache.valid);
371
+ assert.ok(shadowDraws(side).some(draw => draw.object === side.mesh));
372
+ side.node.frozenStatic = false;
373
+ side.step();
374
+ assert.equal(side.events.filter(draw => draw.copy).length, 0);
375
+ assert.ok(shadowDraws(side).some(draw => draw.object === side.mesh));
376
+ },
377
+
378
+ 'other lights see all casters; fade still patches only the colour pass'() {
379
+ const side = setup({ orbit: true });
380
+ const other = new THREE.DirectionalLight();
381
+ other.position.set(6, 18, -6);
382
+ other.castShadow = true;
383
+ side.world.scene.add(other);
384
+ const pass = side.world.renderer.shadowMap.render;
385
+ side.step(WARMUP);
386
+ side.step();
387
+ assert.equal(shadowDraws(side).filter(draw => draw.object === side.mesh).length, 1, 'still caster drawn only for the other light');
388
+ assert.equal(shadowDraws(side).filter(draw => draw.object === side.mover).length, 2);
389
+ const color = side.world.draws.find(draw => draw.name === side.mesh.name && !draw.shadow);
390
+ assert.ok(color.material !== side.mesh.material && color.fade?.length === 2);
391
+ assert.ok(shadowDraws(side).every(draw => draw.material.uniforms?.nearShadowFade === undefined));
392
+ assert.equal(side.world.renderer.shadowMap.render, pass);
393
+ },
394
+
395
+ 'no key, false, wrong type, unsupported callbacks, and unhookable pass stay uncached'() {
396
+ for (const key of [undefined, false, 'true']) {
397
+ const side = setup({ key });
398
+ side.step(WARMUP + 1);
399
+ assert.ok(!cacheOf(side));
400
+ assert.ok(shadowDraws(side).some(draw => draw.object === side.mesh));
401
+ assert.ok(!side.world.gl.sources.some(source => source.includes('cachedDepth')));
402
+ }
403
+ for (const change of [
404
+ side => { side.world.renderer.shadowMap.type = THREE.BasicShadowMap; },
405
+ side => { Object.defineProperty(side.world.renderer.shadowMap, 'render', { writable: false }); },
406
+ side => { side.mesh.onBeforeShadow = () => {}; },
407
+ side => { side.world.scene.onBeforeRender = () => {}; },
408
+ side => { Object.defineProperty(side.mover, 'castShadow', { writable: false }); },
409
+ side => { side.mover.customDepthMaterial = new THREE.MeshDepthMaterial({ depthWrite: false }); },
410
+ ]) {
411
+ const side = setup();
412
+ change(side);
413
+ side.step(WARMUP + 1);
414
+ assert.equal(side.events.filter(draw => draw.copy).length, 0);
415
+ assert.ok(shadowDraws(side).some(draw => draw.object === side.mesh));
416
+ }
417
+ },
418
+
419
+ 'exit, throws and re-entry restore flags/hooks and dispose all cache resources'() {
420
+ for (const kind of ['key', 'distance', 'throw', 'stillthrow', 'reenter', 'dispose', 'world', 'listener']) {
421
+ const side = setup({ orbit: true });
422
+ const pass = side.world.renderer.shadowMap.render;
423
+ side.step(WARMUP);
424
+ const cache = cacheOf(side);
425
+ const resources = [cache.shadow.map, cache.geometry, cache.material, side.world.nearShadows.shadow.map];
426
+ const disposed = resources.map(() => 0);
427
+ resources.forEach((resource, i) => resource.addEventListener('dispose', () => { disposed[i]++; }));
428
+ const own = side.world.sun.shadow;
429
+ if (kind === 'key') side.run.data.engine.shadows.cacheStill = false;
430
+ if (kind === 'distance') side.run.nearShadowDistance = 0;
431
+ if (kind === 'world') side.world.scene.onAfterRender = () => disposeWorld(side.world);
432
+ if (kind === 'listener') resources[0].addEventListener('dispose', () => {
433
+ assert.equal(side.world.sun.shadow, own);
434
+ assert.equal(cache.shadow.map, null);
435
+ assert.equal(cache.triangle, null);
436
+ throw new Error('listener');
437
+ });
438
+ if (['throw', 'stillthrow', 'reenter', 'dispose'].includes(kind)) {
439
+ const direct = side.world.renderer.renderBufferDirect;
440
+ let once = true;
441
+ if (kind === 'stillthrow') side.mesh.material.side = THREE.DoubleSide;
442
+ side.world.renderer.renderBufferDirect = function (...args) {
443
+ if (kind === 'stillthrow' && args[0] === cache.shadow.camera) throw new Error('still failed');
444
+ if (once && args[3] === cache.material) {
445
+ once = false;
446
+ if (kind === 'throw') throw new Error('copy failed');
447
+ if (kind === 'reenter') renderWorld(side.world, side.run);
448
+ if (kind === 'dispose') dropNearShadowsForTest(side.world);
449
+ return;
450
+ }
451
+ return direct.apply(this, args);
452
+ };
453
+ }
454
+ if (kind === 'listener') side.run.nearShadowDistance = 0;
455
+ if (kind === 'stillthrow') side.step(STABLE_FRAMES - 1);
456
+ if (['throw', 'stillthrow', 'listener'].includes(kind)) assert.throws(() => side.step(), /copy failed|still failed|listener/);
457
+ else side.step();
458
+ assert.deepEqual(disposed, [1, 1, 1, 1], kind);
459
+ assert.equal(side.world.sun.shadow, own, kind);
460
+ assert.equal(side.world.renderer.shadowMap.render, pass, kind);
461
+ assert.ok(side.mesh.castShadow && side.mover.castShadow, kind);
462
+ assert.equal(side.world.nearShadows?.depth ?? 0, 0, kind);
463
+ assert.equal(cache.triangle, null, kind);
464
+ }
465
+ },
466
+ };
467
+
468
+ export async function run() {
469
+ let count = 0;
470
+ for (const [name, scenario] of Object.entries(scenarios)) {
471
+ if (process.env.ONLY && !name.includes(process.env.ONLY)) continue;
472
+ try { scenario(); count++; } catch (error) { error.message = `${name}: ${error.message}`; throw error; }
473
+ }
474
+ return count;
475
+ }
476
+
477
+ if (process.argv[1] === new URL(import.meta.url).pathname) console.log(`still shadows: ${await run()} scenarios`);
@@ -10,13 +10,15 @@
10
10
  // rapier's wasm loads async; the system installs immediately and starts
11
11
  // simulating on the first frame after init resolves.
12
12
  import * as THREE from 'three';
13
- import * as RAPIER from '@dimforge/rapier3d-compat';
13
+ import * as RAPIER from '../engine3d/rapier.js';
14
14
  import { remember, sameAs, noteChangedStill } from '../engine3d/unchanged.js';
15
15
  import { isOrbitLook } from '../engine3d/orbitinput.js';
16
16
  import { giveBackOrbitLens } from '../engine3d/orbitlens.js';
17
17
  import { giveBackViewRange } from '../engine3d/viewrange.js';
18
18
  import { leaveSky } from '../engine3d/skylife.js';
19
19
  import { dropShadowFade } from '../engine3d/shadowfade.js';
20
+ import { FrozenPhysics } from '../engine3d/frozenphysics.js';
21
+ import { prepareModelConsumers } from '../engine3d/modelready.js';
20
22
 
21
23
  const FIXED_STEP = 1 / 60;
22
24
  const MAX_STEPS_PER_FRAME = 4;
@@ -85,6 +87,7 @@ export class Physics3DSystem {
85
87
  }
86
88
 
87
89
  reset(runtime) {
90
+ if (this.frozenPhysics) { this.frozenPhysics.dispose(); this.frozenPhysics = null; }
88
91
  // Rapier objects live in wasm -- dropping the JS reference leaks them, so
89
92
  // both the world and its event queue are freed explicitly. Runs on every
90
93
  // scene load (the runtime resets registered systems) and on dispose.
@@ -157,6 +160,23 @@ export class Physics3DSystem {
157
160
 
158
161
  simulate(scene, dt) {
159
162
  if (!rapierReady) return;
163
+ if (this.frozenPhysics && this.frozenPhysics.owner !== scene.frozenActors) {
164
+ this.frozenPhysics.dispose();
165
+ this.frozenPhysics = null;
166
+ }
167
+ if (scene.freezesStatics === true) {
168
+ this.ensureWorld(scene);
169
+ if (typeof this.world.forEachActiveRigidBody === 'function') {
170
+ this.remembered ??= new WeakMap();
171
+ this.rememberedIn = this.world;
172
+ if (this.forces && this.forcesAt !== scene.time) this.forces = null;
173
+ const frozen = this.frozenPhysics ??= new FrozenPhysics(this, scene);
174
+ frozen.simulate(dt);
175
+ return;
176
+ }
177
+ // Older/custom physics providers cannot enumerate awake bodies safely.
178
+ scene.releaseStill();
179
+ }
160
180
  // A system that has held bodies still, or a scene that asks to
161
181
  // (`"engine": { "staticActors": true }`): the same pass, whatever its
162
182
  // kind, seen in and out by the system's keeper (`simulateKept`, below).
@@ -244,6 +264,7 @@ export class Physics3DSystem {
244
264
  removeBody(actorId) {
245
265
  const entry = this.bodies.get(actorId);
246
266
  if (!entry) return;
267
+ this.frozenPhysics?.forgetBody(actorId);
247
268
  if (entry.collider) this.byCollider.delete(entry.collider.handle);
248
269
  this.world.removeRigidBody(entry.body);
249
270
  this.bodies.delete(actorId);
@@ -315,7 +336,7 @@ export class Physics3DSystem {
315
336
  // Snapshot dynamic bodies before each step so rendering can interpolate
316
337
  // between the last two physics states -- without this, bodies advance
317
338
  // only on step frames and stutter on displays faster than 60Hz.
318
- for (const entry of this.bodies.values()) {
339
+ for (const entry of this.frozenPhysics ? this.frozenPhysics.stepEntries() : this.bodies.values()) {
319
340
  if (entry.body.bodyType() !== RAPIER.RigidBodyType.Dynamic) continue;
320
341
  const p = entry.body.translation();
321
342
  const q = entry.body.rotation();
@@ -462,7 +483,7 @@ export class Physics3DSystem {
462
483
  }
463
484
 
464
485
  // `afterBehaviorsSkipping` for a scene that also set `"engine":
465
- // { "staticActors": true }` (world3d.js has the rule; CLAUDE.md the terms).
486
+ // { "staticActors": true }` (world3d.js has the rule; docs/engine-static-actors.md the terms).
466
487
  // A pass is ordinary, every actor as above, unless this system has adopted
467
488
  // the runtime's still set, in this same rapier world; then the still
468
489
  // actors' bodies, which are fixed and where that pass put them, are left
@@ -638,10 +659,13 @@ export class Physics3DSystem {
638
659
  }
639
660
 
640
661
  function emitPair(scene, aId, bId, method) {
662
+ prepareModelConsumers(scene.three, scene, aId);
641
663
  const a = scene.getActor(aId);
642
664
  const b = scene.getActor(bId);
643
665
  if (!a || !b) return;
644
666
  scene.forEachBehavior(a, (instance) => instance[method]?.(a, scene, b));
667
+ // The first actor's callback may add a consumer to the second actor.
668
+ prepareModelConsumers(scene.three, scene, bId);
645
669
  scene.forEachBehavior(b, (instance) => instance[method]?.(b, scene, a));
646
670
  }
647
671
 
@@ -774,7 +798,16 @@ function makeApi(system, runtime) {
774
798
  return {
775
799
  ready: () => rapierReady && Boolean(system.world),
776
800
  debugRender: () => (system.world ? system.world.debugRender() : null),
777
- bodyOf,
801
+ bodyOf: (actor) => {
802
+ // A raw Rapier handle allows writes outside our component/API hooks.
803
+ // Keep that body in the checked pass from now on.
804
+ if (runtime.freezesStatics) {
805
+ runtime.frozenActors.release(runtime.getActor(idOf(actor)));
806
+ system.frozenPhysics?.exposed.add(idOf(actor));
807
+ runtime.touch(actor);
808
+ }
809
+ return bodyOf(actor);
810
+ },
778
811
  mass: (actor) => bodyOf(actor)?.mass() ?? 0,
779
812
  getVelocity: (actor) => {
780
813
  const v = bodyOf(actor)?.linvel();
@@ -3,11 +3,11 @@
3
3
  "imports": {
4
4
  "castle.base": {
5
5
  "deckId": "yRcmH4_aYllE",
6
- "version": "2026-10-07T03:41:20.671Z"
6
+ "version": "2026-10-18T06:37:02.597Z"
7
7
  }
8
8
  },
9
9
  "autoUpdateWhenImported": true,
10
10
  "deckId": "xFVr-afOLuUQ",
11
11
  "cardId": "w6G45sy3_P_m",
12
- "publishedVersion": "2026-10-07T03:43:17.687Z"
12
+ "publishedVersion": "2026-10-18T06:38:41.691Z"
13
13
  }