castle-web-cli 0.4.233 → 0.4.235

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 (383) 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 +266 -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 +68 -5
  39. package/kits/base/sdk/hubRejoin.d.ts +4 -0
  40. package/kits/base/sdk/hubRejoin.js +15 -0
  41. package/kits/base/sdk/multiplayer.d.ts +7 -1
  42. package/kits/base/sdk/multiplayer.js +147 -40
  43. package/kits/base/sdk/multiplayerProtocol.d.ts +2 -0
  44. package/kits/base/sdk/party.d.ts +23 -0
  45. package/kits/base/sdk/party.js +91 -0
  46. package/kits/base/sdk/reconnectBudget.d.ts +23 -0
  47. package/kits/base/sdk/reconnectBudget.js +96 -0
  48. package/kits/base/sdk/save.d.ts +38 -1
  49. package/kits/base/sdk/save.js +79 -6
  50. package/kits/base/sdk/server/hub.d.ts +31 -1
  51. package/kits/base/sdk/server/hub.js +50 -3
  52. package/kits/base/sdk/server/platformHandle.d.ts +13 -1
  53. package/kits/base/sdk/server/storage.d.ts +4 -0
  54. package/kits/base/sdk/server/storage.js +19 -3
  55. package/kits/base/sdk/server/wrapper.d.ts +7 -1
  56. package/kits/base/sdk/server/wrapper.js +10 -1
  57. package/kits/base/sdk/social.d.ts +9 -0
  58. package/kits/base/sdk/social.js +5 -0
  59. package/kits/hub-game/CLAUDE.md +123 -3
  60. package/kits/hub-game/README.md +63 -0
  61. package/kits/hub-game/castle.json +5 -5
  62. package/kits/hub-game/code/client/act.js +312 -0
  63. package/kits/hub-game/code/client/actionLayout.js +147 -0
  64. package/kits/hub-game/code/client/actionOverflow.js +556 -0
  65. package/kits/hub-game/code/client/arrivalCamera.js +50 -0
  66. package/kits/hub-game/code/client/askSlot.js +117 -0
  67. package/kits/hub-game/code/client/avatar.js +4 -2
  68. package/kits/hub-game/code/client/avatarShare.js +2 -0
  69. package/kits/hub-game/code/client/backVisibility.js +13 -0
  70. package/kits/hub-game/code/client/ballot.js +15 -10
  71. package/kits/hub-game/code/client/build.js +16 -0
  72. package/kits/hub-game/code/client/chat.js +41 -5
  73. package/kits/hub-game/code/client/chatModeration.js +5 -0
  74. package/kits/hub-game/code/client/chrome.js +1148 -258
  75. package/kits/hub-game/code/client/crowdNames.js +241 -0
  76. package/kits/hub-game/code/client/decor.js +10 -4
  77. package/kits/hub-game/code/client/defaultEnvironment.js +194 -0
  78. package/kits/hub-game/code/client/doorErrors.js +39 -0
  79. package/kits/hub-game/code/client/fall.js +18 -0
  80. package/kits/hub-game/code/client/farAvatars.js +233 -0
  81. package/kits/hub-game/code/client/firstJoin.js +9 -2
  82. package/kits/hub-game/code/client/fpsTelemetry.js +50 -0
  83. package/kits/hub-game/code/client/frameBatch.js +5 -0
  84. package/kits/hub-game/code/client/grab.js +31 -11
  85. package/kits/hub-game/code/client/hookLayer.js +87 -8
  86. package/kits/hub-game/code/client/hudCopy.js +51 -0
  87. package/kits/hub-game/code/client/hudRate.js +20 -0
  88. package/kits/hub-game/code/client/idle.js +14 -2
  89. package/kits/hub-game/code/client/invites.js +231 -0
  90. package/kits/hub-game/code/client/joinError.js +9 -0
  91. package/kits/hub-game/code/client/labelsNear.js +31 -2
  92. package/kits/hub-game/code/client/landscapeLayout.js +17 -0
  93. package/kits/hub-game/code/client/layoutCache.js +264 -0
  94. package/kits/hub-game/code/client/loadTelemetry.js +20 -0
  95. package/kits/hub-game/code/client/loadingCover.js +148 -0
  96. package/kits/hub-game/code/client/loadingEntry.js +8 -0
  97. package/kits/hub-game/code/client/menuRows.js +43 -0
  98. package/kits/hub-game/code/client/modelReady.js +7 -0
  99. package/kits/hub-game/code/client/padCueArrival.js +23 -0
  100. package/kits/hub-game/code/client/padCues.js +112 -0
  101. package/kits/hub-game/code/client/padOccupancy.js +88 -0
  102. package/kits/hub-game/code/client/padReadability.js +26 -0
  103. package/kits/hub-game/code/client/padRings.js +69 -0
  104. package/kits/hub-game/code/client/pushVisit.js +14 -0
  105. package/kits/hub-game/code/client/quality.js +205 -0
  106. package/kits/hub-game/code/client/qualityEntry.js +55 -0
  107. package/kits/hub-game/code/client/safeLayout.js +338 -0
  108. package/kits/hub-game/code/client/safeStyle.js +42 -0
  109. package/kits/hub-game/code/client/say.js +12 -3
  110. package/kits/hub-game/code/client/shot.js +64 -10
  111. package/kits/hub-game/code/client/shotFit.js +56 -0
  112. package/kits/hub-game/code/client/signIn.js +28 -0
  113. package/kits/hub-game/code/client/state.js +53 -0
  114. package/kits/hub-game/code/client/talk.js +209 -45
  115. package/kits/hub-game/code/client/tiers.js +68 -66
  116. package/kits/hub-game/code/client/together.js +7 -2
  117. package/kits/hub-game/code/client/weakestLookBake.js +92 -0
  118. package/kits/hub-game/code/client/weakestTier.js +295 -0
  119. package/kits/hub-game/code/client/worldLabels.js +241 -0
  120. package/kits/hub-game/code/client/yours.js +10 -9
  121. package/kits/hub-game/code/npcDisplayText.js +55 -0
  122. package/kits/hub-game/code/server/act.js +124 -0
  123. package/kits/hub-game/code/server/actions.js +6 -1
  124. package/kits/hub-game/code/server/actors.js +2 -1
  125. package/kits/hub-game/code/server/analytics.js +83 -0
  126. package/kits/hub-game/code/server/anonymousEntry.js +49 -0
  127. package/kits/hub-game/code/server/arrivalPose.js +36 -0
  128. package/kits/hub-game/code/server/companion.js +28 -3
  129. package/kits/hub-game/code/server/doorAnalytics.js +52 -0
  130. package/kits/hub-game/code/server/earned.js +22 -5
  131. package/kits/hub-game/code/server/frameBatch.js +183 -0
  132. package/kits/hub-game/code/server/friendsAmong.js +49 -9
  133. package/kits/hub-game/code/server/history.js +2 -0
  134. package/kits/hub-game/code/server/hub.js +1306 -95
  135. package/kits/hub-game/code/server/idle.js +30 -1
  136. package/kits/hub-game/code/server/index.js +26 -4
  137. package/kits/hub-game/code/server/invites.js +19 -0
  138. package/kits/hub-game/code/server/labels.js +9 -1
  139. package/kits/hub-game/code/server/loadAbandon.js +106 -0
  140. package/kits/hub-game/code/server/manifest.js +211 -3
  141. package/kits/hub-game/code/server/menu.js +31 -3
  142. package/kits/hub-game/code/server/npcs.js +226 -64
  143. package/kits/hub-game/code/server/observe.js +408 -0
  144. package/kits/hub-game/code/server/padOccupancy.js +85 -0
  145. package/kits/hub-game/code/server/players.js +9 -1
  146. package/kits/hub-game/code/server/resumePose.js +152 -0
  147. package/kits/hub-game/code/server/say.js +1 -1
  148. package/kits/hub-game/code/server/standing.js +4 -5
  149. package/kits/hub-game/code/server/storageLimit.js +187 -0
  150. package/kits/hub-game/code/server/vis.js +67 -5
  151. package/kits/hub-game/code/shared/act.js +35 -0
  152. package/kits/hub-game/code/shared/danceIdle.js +28 -0
  153. package/kits/hub-game/code/shared/loadStages.js +12 -0
  154. package/kits/hub-game/code/shared/quality.js +74 -0
  155. package/kits/hub-game/code/shared/say.js +2 -0
  156. package/kits/hub-game/code/shared/shot.js +35 -1
  157. package/kits/hub-game/code/systems/hub.js +970 -169
  158. package/kits/hub-game/docs/analytics.md +279 -0
  159. package/kits/hub-game/docs/contract.md +1259 -42
  160. package/kits/hub-game/docs/home-pieces.md +9 -2
  161. package/kits/hub-game/docs/observed-progress.md +252 -0
  162. package/kits/hub-game/main.jsx +2 -0
  163. package/kits/hub-game/package-lock.json +10 -3
  164. package/kits/hub-game/package.json +6 -3
  165. package/kits/hub-game/play/player.js +142 -0
  166. package/kits/hub-game/play/registry.js +47 -0
  167. package/kits/hub-game/play.jsx +37 -0
  168. package/kits/hub-game/scripts/check.mjs +39 -5
  169. package/kits/hub-game/scripts/companion-follower-wire.json +1 -1
  170. package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +11 -0
  171. package/kits/hub-game/scripts/fixtures/decor-keyless.json +5 -5
  172. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +3 -0
  173. package/kits/hub-game/scripts/fixtures/fake-dom.mjs +19 -3
  174. package/kits/hub-game/scripts/fixtures/interest-legacy.json +3 -3
  175. package/kits/hub-game/scripts/fixtures/vis-shared-wire.json +1 -1
  176. package/kits/hub-game/scripts/pose-storage-fixture.mjs +46 -0
  177. package/kits/hub-game/scripts/test-act-client.mjs +186 -0
  178. package/kits/hub-game/scripts/test-act.mjs +171 -0
  179. package/kits/hub-game/scripts/test-action-layout.mjs +80 -0
  180. package/kits/hub-game/scripts/test-action-observers.mjs +46 -0
  181. package/kits/hub-game/scripts/test-actions-client.mjs +367 -2
  182. package/kits/hub-game/scripts/test-actors.mjs +20 -7
  183. package/kits/hub-game/scripts/test-analytics.mjs +76 -0
  184. package/kits/hub-game/scripts/test-anonymous-entry.mjs +28 -0
  185. package/kits/hub-game/scripts/test-arrival-pose-server.mjs +196 -0
  186. package/kits/hub-game/scripts/test-arrival-pose.mjs +24 -0
  187. package/kits/hub-game/scripts/test-ask-slot.mjs +85 -0
  188. package/kits/hub-game/scripts/test-avatar-wire.mjs +49 -10
  189. package/kits/hub-game/scripts/test-avatar.mjs +44 -0
  190. package/kits/hub-game/scripts/test-back-visibility.mjs +82 -0
  191. package/kits/hub-game/scripts/test-ballot.mjs +11 -4
  192. package/kits/hub-game/scripts/test-ban-join.mjs +121 -13
  193. package/kits/hub-game/scripts/test-build.mjs +20 -2
  194. package/kits/hub-game/scripts/test-chat.mjs +206 -5
  195. package/kits/hub-game/scripts/test-companion-chat.mjs +20 -2
  196. package/kits/hub-game/scripts/test-control-layout-dom.mjs +120 -0
  197. package/kits/hub-game/scripts/test-crowd-names.mjs +205 -0
  198. package/kits/hub-game/scripts/test-decor-client.mjs +45 -4
  199. package/kits/hub-game/scripts/test-decor.mjs +7 -0
  200. package/kits/hub-game/scripts/test-default-environment-root.mjs +95 -0
  201. package/kits/hub-game/scripts/test-default-environment.mjs +267 -0
  202. package/kits/hub-game/scripts/test-door-analytics.mjs +58 -0
  203. package/kits/hub-game/scripts/test-door-jump.mjs +100 -0
  204. package/kits/hub-game/scripts/test-earned.mjs +33 -3
  205. package/kits/hub-game/scripts/test-far-avatars.mjs +340 -0
  206. package/kits/hub-game/scripts/test-fps-telemetry.mjs +112 -0
  207. package/kits/hub-game/scripts/test-frame-batch.mjs +252 -0
  208. package/kits/hub-game/scripts/test-fresh-friends.mjs +118 -0
  209. package/kits/hub-game/scripts/test-grab-orbit.mjs +47 -4
  210. package/kits/hub-game/scripts/test-high-only.mjs +170 -0
  211. package/kits/hub-game/scripts/test-hub-ops.mjs +321 -2
  212. package/kits/hub-game/scripts/test-hub-trip.mjs +879 -11
  213. package/kits/hub-game/scripts/test-hud-clear.mjs +162 -59
  214. package/kits/hub-game/scripts/test-hud-defects-dom.mjs +100 -0
  215. package/kits/hub-game/scripts/test-hud-rate.mjs +224 -0
  216. package/kits/hub-game/scripts/test-hud-safe-visibility-dom.mjs +83 -0
  217. package/kits/hub-game/scripts/test-idle.mjs +66 -0
  218. package/kits/hub-game/scripts/test-interest-cells.mjs +20 -0
  219. package/kits/hub-game/scripts/test-interest.mjs +15 -0
  220. package/kits/hub-game/scripts/test-invites-client.mjs +430 -0
  221. package/kits/hub-game/scripts/test-invites.mjs +109 -0
  222. package/kits/hub-game/scripts/test-labels.mjs +71 -3
  223. package/kits/hub-game/scripts/test-landscape-layout.mjs +194 -0
  224. package/kits/hub-game/scripts/test-list-scroll-dom.mjs +49 -0
  225. package/kits/hub-game/scripts/test-load-abandon.mjs +246 -0
  226. package/kits/hub-game/scripts/test-loading-cover.mjs +162 -0
  227. package/kits/hub-game/scripts/test-manifest.mjs +265 -0
  228. package/kits/hub-game/scripts/test-menu-client.mjs +105 -0
  229. package/kits/hub-game/scripts/test-menu.mjs +23 -0
  230. package/kits/hub-game/scripts/test-npcs.mjs +917 -10
  231. package/kits/hub-game/scripts/test-observed.mjs +745 -0
  232. package/kits/hub-game/scripts/test-pad-cues.mjs +304 -0
  233. package/kits/hub-game/scripts/test-pad-occupancy.mjs +177 -0
  234. package/kits/hub-game/scripts/test-picker.mjs +234 -7
  235. package/kits/hub-game/scripts/test-placement-cache.mjs +690 -0
  236. package/kits/hub-game/scripts/test-progress-reset.mjs +559 -0
  237. package/kits/hub-game/scripts/test-push-visit.mjs +26 -0
  238. package/kits/hub-game/scripts/test-quality.mjs +385 -0
  239. package/kits/hub-game/scripts/test-rehello.mjs +699 -5
  240. package/kits/hub-game/scripts/test-resume-action-order.mjs +598 -0
  241. package/kits/hub-game/scripts/test-resume-held.mjs +239 -0
  242. package/kits/hub-game/scripts/test-resume-pose.mjs +142 -0
  243. package/kits/hub-game/scripts/test-safe-events-dom.mjs +116 -0
  244. package/kits/hub-game/scripts/test-safe-layout.mjs +330 -0
  245. package/kits/hub-game/scripts/test-say.mjs +1 -1
  246. package/kits/hub-game/scripts/test-shot.mjs +145 -0
  247. package/kits/hub-game/scripts/test-signin-client.mjs +45 -0
  248. package/kits/hub-game/scripts/test-soundscape.mjs +22 -17
  249. package/kits/hub-game/scripts/test-standing.mjs +35 -2
  250. package/kits/hub-game/scripts/test-storage-limit.mjs +333 -0
  251. package/kits/hub-game/scripts/test-stuck.mjs +5 -4
  252. package/kits/hub-game/scripts/test-talk-overlay-dom.mjs +130 -0
  253. package/kits/hub-game/scripts/test-tiers-render.mjs +86 -13
  254. package/kits/hub-game/scripts/test-tiers.mjs +7 -8
  255. package/kits/hub-game/scripts/test-vis.mjs +433 -6
  256. package/kits/hub-game/scripts/test-weakest-tier.mjs +924 -0
  257. package/kits/hub-game/scripts/test-world-labels.mjs +367 -0
  258. package/kits/hub-game/scripts/test-yours-chrome.mjs +50 -6
  259. package/kits/hub-game/scripts/test-yours.mjs +39 -8
  260. package/kits/multiplayer-3d/castle.json +5 -5
  261. package/kits/multiplayer-3d/code/client/joinFailure.js +27 -0
  262. package/kits/multiplayer-3d/code/client/resumeGate.js +139 -0
  263. package/kits/multiplayer-3d/code/systems/multiplayer.js +369 -30
  264. package/kits/multiplayer-3d/package-lock.json +8 -1
  265. package/kits/multiplayer-3d/package.json +2 -1
  266. package/kits/multiplayer-3d/scripts/test-join-watchdog.mjs +436 -0
  267. package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +624 -0
  268. package/kits/physics-2d/CLAUDE.md +10 -1
  269. package/kits/physics-2d/castle.json +2 -2
  270. package/kits/physics-2d/engine/frozenActors.js +233 -0
  271. package/kits/physics-2d/engine/scene.js +87 -5
  272. package/kits/physics-2d/eslint.config.js +1 -1
  273. package/kits/physics-2d/play/behaviors/AnalogStick.js +198 -0
  274. package/kits/physics-2d/play/behaviors/Camera.js +40 -0
  275. package/kits/physics-2d/play/behaviors/Collider.js +122 -0
  276. package/kits/physics-2d/play/behaviors/Draggable.js +115 -0
  277. package/kits/physics-2d/play/behaviors/Goal.js +46 -0
  278. package/kits/physics-2d/play/behaviors/Joints.js +126 -0
  279. package/kits/physics-2d/play/behaviors/Layout.js +71 -0
  280. package/kits/physics-2d/play/behaviors/RigidBody.js +57 -0
  281. package/kits/physics-2d/play/behaviors/Slingshot.js +142 -0
  282. package/kits/physics-2d/play/behaviors/SoundPlayer.js +263 -0
  283. package/kits/physics-2d/play/behaviors/Sprite.js +406 -0
  284. package/kits/physics-2d/play/behaviors/Style.js +209 -0
  285. package/kits/physics-2d/play/behaviors/Text.js +85 -0
  286. package/kits/physics-2d/play/behaviors/Video.js +93 -0
  287. package/kits/physics-3d/CLAUDE.md +25 -1651
  288. package/kits/physics-3d/behaviors/Body.jsx +3 -0
  289. package/kits/physics-3d/behaviors/Model.jsx +3 -0
  290. package/kits/physics-3d/behaviors/Player.jsx +35 -18
  291. package/kits/physics-3d/behaviors/Shape.jsx +3 -0
  292. package/kits/physics-3d/behaviors/Solid.jsx +3 -0
  293. package/kits/physics-3d/behaviors/Transform.jsx +3 -0
  294. package/kits/physics-3d/castle.json +3 -3
  295. package/kits/physics-3d/docs/engine-camera.md +542 -0
  296. package/kits/physics-3d/docs/engine-frame-cap.md +136 -0
  297. package/kits/physics-3d/docs/engine-load.md +149 -0
  298. package/kits/physics-3d/docs/engine-look.md +114 -0
  299. package/kits/physics-3d/docs/engine-shadows.md +372 -0
  300. package/kits/physics-3d/docs/engine-skip-work.md +187 -0
  301. package/kits/physics-3d/docs/engine-sky.md +198 -0
  302. package/kits/physics-3d/docs/engine-static-actors.md +226 -0
  303. package/kits/physics-3d/docs/engine-view.md +37 -0
  304. package/kits/physics-3d/docs/pxmodel-format.md +1 -1
  305. package/kits/physics-3d/engine3d/PlayOnly3D.jsx +5 -1
  306. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +19 -333
  307. package/kits/physics-3d/engine3d/actornode.js +1 -0
  308. package/kits/physics-3d/engine3d/branches.js +3 -13
  309. package/kits/physics-3d/engine3d/cage.js +2 -7
  310. package/kits/physics-3d/engine3d/cageops.js +2 -17
  311. package/kits/physics-3d/engine3d/dataBehaviors.js +12 -0
  312. package/kits/physics-3d/engine3d/framecap.js +4 -1
  313. package/kits/physics-3d/engine3d/frozenphysics.js +140 -0
  314. package/kits/physics-3d/engine3d/frozenstatics.js +273 -0
  315. package/kits/physics-3d/engine3d/gait.js +8 -0
  316. package/kits/physics-3d/engine3d/initialModelFiles.js +18 -0
  317. package/kits/physics-3d/engine3d/look.js +7 -0
  318. package/kits/physics-3d/engine3d/modelFiles.js +3 -17
  319. package/kits/physics-3d/engine3d/modelMath.js +49 -0
  320. package/kits/physics-3d/engine3d/modelready.js +16 -0
  321. package/kits/physics-3d/engine3d/motion.js +3 -3
  322. package/kits/physics-3d/engine3d/nearshadows.js +77 -10
  323. package/kits/physics-3d/engine3d/orbitinput.js +59 -25
  324. package/kits/physics-3d/engine3d/partgeometry.js +1 -16
  325. package/kits/physics-3d/engine3d/paths.js +1 -9
  326. package/kits/physics-3d/engine3d/playTimings.js +50 -0
  327. package/kits/physics-3d/engine3d/playerRun.js +372 -0
  328. package/kits/physics-3d/engine3d/pxmodel.js +3 -3
  329. package/kits/physics-3d/engine3d/rapier.js +27 -0
  330. package/kits/physics-3d/engine3d/scatter.js +1 -11
  331. package/kits/physics-3d/engine3d/shadowfade.js +23 -15
  332. package/kits/physics-3d/engine3d/sky.js +1 -1
  333. package/kits/physics-3d/engine3d/squarefirst.js +177 -0
  334. package/kits/physics-3d/engine3d/stillshadows.js +399 -0
  335. package/kits/physics-3d/engine3d/sweep.js +1 -25
  336. package/kits/physics-3d/engine3d/world3d.js +468 -18
  337. package/kits/physics-3d/eslint.config.js +2 -1
  338. package/kits/physics-3d/main.jsx +6 -3
  339. package/kits/physics-3d/package-lock.json +7 -0
  340. package/kits/physics-3d/package.json +5 -1
  341. package/kits/physics-3d/play/behaviors/Body.js +31 -0
  342. package/kits/physics-3d/play/behaviors/Door.js +37 -0
  343. package/kits/physics-3d/play/behaviors/Lookable.js +16 -0
  344. package/kits/physics-3d/play/behaviors/Model.js +23 -0
  345. package/kits/physics-3d/play/behaviors/Pickup.js +46 -0
  346. package/kits/physics-3d/play/behaviors/Player.js +1204 -0
  347. package/kits/physics-3d/play/behaviors/Shape.js +47 -0
  348. package/kits/physics-3d/play/behaviors/Solid.js +16 -0
  349. package/kits/physics-3d/play/behaviors/Transform.js +29 -0
  350. package/kits/physics-3d/pnpm-lock.yaml +8 -0
  351. package/kits/physics-3d/scripts/bench-shadow-fade.mjs +37 -0
  352. package/kits/physics-3d/scripts/build-rapier-gz.mjs +56 -0
  353. package/kits/physics-3d/scripts/frozen-statics-fixture.mjs +141 -0
  354. package/kits/physics-3d/scripts/test-camera-follow.mjs +5 -1
  355. package/kits/physics-3d/scripts/test-camera-orbit.mjs +52 -4
  356. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +1 -1
  357. package/kits/physics-3d/scripts/test-empty-gait-hints.mjs +89 -0
  358. package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +6 -3
  359. package/kits/physics-3d/scripts/test-frame-cap.mjs +1 -1
  360. package/kits/physics-3d/scripts/test-frozen-nested.mjs +49 -0
  361. package/kits/physics-3d/scripts/test-frozen-statics-legacy-physics2d.mjs +123 -0
  362. package/kits/physics-3d/scripts/test-frozen-statics.mjs +434 -0
  363. package/kits/physics-3d/scripts/test-look-bake.mjs +1 -1
  364. package/kits/physics-3d/scripts/test-near-shadows.mjs +2 -2
  365. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +88 -7
  366. package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +40 -3
  367. package/kits/physics-3d/scripts/test-orbit-shot.mjs +75 -1
  368. package/kits/physics-3d/scripts/test-rapier-gz.mjs +106 -0
  369. package/kits/physics-3d/scripts/test-sky.mjs +1 -1
  370. package/kits/physics-3d/scripts/test-square-first.mjs +921 -0
  371. package/kits/physics-3d/scripts/test-static-actors.mjs +3 -1
  372. package/kits/physics-3d/scripts/test-static-physics.mjs +4 -1
  373. package/kits/physics-3d/scripts/test-static-scenery.mjs +5 -2
  374. package/kits/physics-3d/scripts/test-steady-hover.mjs +5 -2
  375. package/kits/physics-3d/scripts/test-still-shadows.mjs +477 -0
  376. package/kits/physics-3d/systems/physics3d.js +37 -4
  377. package/kits/real-time/castle.json +2 -2
  378. package/kits/real-time/code/client/connection.js +33 -10
  379. package/kits/real-time/code/client/gameHooks.js +2 -0
  380. package/kits/real-time/code/client/joinOverlay.js +9 -4
  381. package/kits/real-time/code/server/session.js +6 -4
  382. package/kits/real-time/package-lock.json +1 -1
  383. package/package.json +2 -2
@@ -0,0 +1,372 @@
1
+ # Scene key: engine.shadows
2
+
3
+ The physics-3d kit's CLAUDE.md Quick reference points here. The key sits in
4
+ the `engine` object at a scene file's top level, beside `ground`.
5
+
6
+ - `"engine": { "shadows": { "distance": 40, "cacheStill": true } }`
7
+ additionally reuses the depths of still casters. Omit `cacheStill` (or set
8
+ it to `false`) for the existing behaviour, with no cache allocations,
9
+ traversal, shader, or draws. `cacheStill` alone does nothing without a
10
+ valid near-shadow `distance`.
11
+
12
+ This uses the engine's still tracking, rather than an actor's `static`
13
+ mark alone: an adopted, frozen node from `staticActors` with
14
+ `skipUnchangedActors` (or the `frozenStatics` path). Touch an actor before
15
+ changing it, as required by those modes. Touched/thawed actors, newly
16
+ spawned actors, and animated models cast live shadows every frame.
17
+ Skinned, morphed, instanced, custom-depth, alpha-tested, displaced,
18
+ clipped, and wireframe casters also stay live, even under a frozen node.
19
+
20
+ A change of the existing texel-snapped box, depth range/lens, light
21
+ projection, runtime's still version/frozen epoch, or selected still
22
+ casters invalidates the cache. Its complete key must then match for
23
+ **three consecutive engine frames** (`STABLE_FRAMES = 3`) before a build.
24
+ On a miss or while waiting, the frame uses the ordinary shadow pass:
25
+ **no copy, no extra depth pass, and no still-map rebuild**. Continuous
26
+ camera movement therefore adds only key computation. Repeated renders
27
+ within one engine frame do not count as additional stable frames.
28
+ Selection includes visibility, layers, `castShadow`, the view-slice
29
+ frustum, matrices, geometry uploads/groups/draw range, and material depth
30
+ settings. A small camera move can reuse the map while those inputs remain
31
+ equal. Selection changes also invalidate inside one grid cell: caching
32
+ the whole box instead would change shadows outside the current view slice.
33
+ The picture and snapping are the same as ordinary near shadows.
34
+
35
+ On a cache hit or qualified build frame, the live shadow target is cleared
36
+ normally, then a fullscreen triangle copies the cached packed colour
37
+ **and hardware depth** into it.
38
+ Movers draw on top with the ordinary depth test and no further clear, so
39
+ movers occlude scenery correctly and leave no old shadows behind. On a
40
+ rebuild, a shadow-only pass draws still casters into the cache first. The
41
+ sun's own shadow/camera/map/target remain untouched; private shadows and
42
+ temporary caster filtering exist only inside the engine's render call.
43
+ Filtering ends before another light's shadows or any colour draw. The
44
+ existing orbit shadow-fade hook restores original materials before both
45
+ depth passes; its receiver shaders and fade stay unchanged.
46
+
47
+ Camera/scene identity and camera layers are part of the key. A render
48
+ using another actual camera or scene bypasses the cache entirely and
49
+ uses the ordinary shadow pass, without changing the primary view's key
50
+ or stability count. This includes a nested render from a mesh's
51
+ `onBeforeRender`. Selection and rebuilding use the actual render camera
52
+ and scene passed to the shadow hook. The private copy triangle enables
53
+ all layers so its geometry uploads even when the camera, sun, and casters
54
+ use layer 1 (or any layer other than 0). It is attached for the primary
55
+ camera's object walk before a build can qualify, submits no colour draw,
56
+ and detaches at the primary shadow pass. Unrelated renders leave it for
57
+ the primary camera's walk.
58
+
59
+ Cost: one extra map at the near map's resolution (RGBA8 plus a depth
60
+ texture, about 8 bytes per texel), one fullscreen draw per cache hit/build,
61
+ and a visible-scene walk plus still-caster comparisons. Key buffers and
62
+ selection arrays are reused; steady key computation allocates no arrays,
63
+ sets or per-caster descriptors. A new caster is inspected once; later flag
64
+ locks are checked before copying or drawing. A qualified build draws each
65
+ still caster once into the cache and each mover once into the live map,
66
+ rather than drawing either twice. This reduces draw submission when the
67
+ view and still scenery stay stable; it does not reduce scene updates or
68
+ the fade's own walk/material swaps. Frequent box/selection changes keep ordinary shadow
69
+ submission until the full key settles again.
70
+
71
+ The implementation is pinned to three.js r180's shadow-pass ordering. A
72
+ different revision, reversed/logarithmic depth, or a shadow pass that
73
+ cannot accept a temporary hook uses ordinary near shadows. A scene with
74
+ its own `onBeforeRender` also draws uncached. Custom shadow callbacks or
75
+ non-writable caster flags make the frame uncached, preserving their
76
+ behaviour. Custom depth materials with compile hooks or nonstandard depth
77
+ tests, writes, or blending also draw the frame uncached: reordering them
78
+ around still casters could change the picture. The ordinary near-mode
79
+ plain-frame guards below still apply. Removing either key, a fallback out
80
+ of near mode, a render throw,
81
+ re-entry, or world disposal frees the extra target, copy geometry and
82
+ material along with the near map. Disposal listeners see resources already
83
+ detached, original caster flags, and the sun's original shadow.
84
+
85
+ - `"engine": { "shadows": { "distance": 40 } }` at the scene file's top level
86
+ (the same `engine` object) asks the engine to draw the sun's shadows where
87
+ they can be seen, near the camera, rather than in the sun's fixed box.
88
+ Without it the sun's shadow camera is a fixed 150 x 120 m box round the
89
+ origin, so every caster under the box is drawn a second time each frame
90
+ wherever the player stands, and a scene larger than the box has no shadows
91
+ outside it. The terms:
92
+ > With the key absent, a scene is drawn exactly as before: the same shadow
93
+ > camera, map, `castShadow` flags and render calls. On a frame the mode
94
+ > draws, everything the camera sees within `distance` metres (measured along
95
+ > the way it looks) is shadowed as it would be under a box that covered it,
96
+ > with texels exactly the size the sun's own are and the same softness and
97
+ > bias. Shadows are complete out to `distance` for casters inside the depth
98
+ > range below; a point farther off may or may not be shadowed, and nothing
99
+ > cuts shadows off there.
100
+
101
+ Past `distance` on a frame the mode draws, a point may or may not be
102
+ shadowed (a caster kept for a nearer point shadows farther ones too), and
103
+ past the edge of the mode's box nothing is: three.js leaves a point
104
+ outside the shadow map lit, and the sun's own shadow is not drawn on such
105
+ a frame. Under a fixed camera looking down that edge is off screen.
106
+
107
+ Under the orbit camera key as well (docs/engine-camera.md), which tilts the camera to the
108
+ horizontal where that edge would be a hard line across the ground, a frame
109
+ the mode draws fades the sun's shadow out toward it
110
+ (`engine3d/shadowfade.js`): whole up to 0.75 of the mode's reach (the
111
+ distance it could fit, along the way the camera looks), gone at the reach,
112
+ smoothstep between, to full sun, which is what lies beyond. How:
113
+ > The fade writes no material, not even for a moment, and the scene's,
114
+ > the faded meshes' and the faded materials' own callbacks never meet a
115
+ > variant. What gets one: a material whose class is exactly one of
116
+ > three's own lit ones (standard, physical, lambert, phong, toon; a
117
+ > subclass is not faded), alone on its mesh (a mesh with an array of
118
+ > materials is not faded), whose hooks, listeners and mesh are plain
119
+ > data (read from property descriptors: one behind a deck's accessor is
120
+ > not faded, and the fade never calls a getter), and whose `onBeforeCompile`,
121
+ > `customProgramCacheKey` and `onBeforeRender` are three's own or the
122
+ > kit's (`engine3d/kithooks.js`: look.js, optimize.js,
123
+ > materialpresets.js), on a mesh that receives shadows and has no
124
+ > `onBeforeRender` or `onAfterRender` of its own; and a frame is faded
125
+ > only when the scene has no `onBeforeRender` of its own. Anything else
126
+ > is drawn as it is, unfaded. A variant is a separate material object to
127
+ > the renderer whose every property, read or written, is the original's:
128
+ > its prototype, shared per material class, has a forwarding accessor for
129
+ > each property and accessor of the class, over a proxy that answers
130
+ > anything else from the original; so deck code inside the frame that
131
+ > reaches a variant (an LOD's `update`, a callback installed mid-frame and
132
+ > handed the material three listed) and three's own side flip and version
133
+ > bumps write the original as they would without the key. Its events and
134
+ > `dispose` are the original's too; only the renderer's own dispose
135
+ > listener for the variant's program (known by its function, learned
136
+ > once per renderer by compiling a private material and finishing its
137
+ > program's first-use initialization before disposing it) is held by the
138
+ > variant (and added to
139
+ > the original, where the renderer drawing it would have it), and the
140
+ > variant's program is let go of when the variant is disposed or dropped
141
+ > or the original is disposed (seen by a dispose listener gone from the
142
+ > original, or by the renderer's own entry for the original replaced,
143
+ > when the world's renderer also draws it elsewhere). Its own: an id, that listener, and the
144
+ > shader hooks held as they were when it was made (the held
145
+ > `onBeforeCompile` then the fade; the held key plus
146
+ > `|near-shadow-fade`). Before each faded frame it is drawn in it is
147
+ > dropped if the original has other hooks or is no longer one to fade. A
148
+ > hook the original is given inside a frame is never run for the
149
+ > variant: it compiles with the held hook under a key of its own and is
150
+ > dropped next frame. A property defined on a variant reaches the
151
+ > original after the frame; deck code that compares a variant by
152
+ > identity with its original, asks it `key in` or deletes through it sees
153
+ > another object. The fade's
154
+ > uniform is on the variants only. The variants go on the meshes right
155
+ > before the mode's one render call, and come off in a hook on the world
156
+ > renderer's `shadowMap.render`, which three calls on every render after
157
+ > listing the draws and before drawing any, whatever the shadow
158
+ > settings; the hook comes off when the sun gets its own shadow back,
159
+ > whatever the render did (one a deck replaced meanwhile stays replaced,
160
+ > and ours, if it still calls it, only calls the pass it had). So the
161
+ > frame's own draws use the variants and every render after its list of
162
+ > draws sees the originals. Accepted, inside the keyed world's own frame
163
+ > only: a deck's own sort comparator (`renderer.setOpaqueSort` /
164
+ > `setTransparentSort`) is handed render items holding the variants. A
165
+ > variant not drawn for 60 faded frames is disposed; all are disposed on
166
+ > a scene load, an editor frame, any frame of a scene without both keys
167
+ > and `disposeWorld`. The fade is for the first casting directional
168
+ > light, and a frame is faded only when that is the sun. Not covered: a
169
+ > hook or callback that changes in place an object the original holds by
170
+ > reference (its colour, a texture, its defines) changes it for every
171
+ > world, as it would without the key. A material that is itself a Proxy
172
+ > can observe the fade's reads through its traps. Deck getters with side
173
+ > effects on properties three reads during a render (`isMesh`, `visible`,
174
+ > `children`, `matrixWorld`, `layers`, ...) may run extra times in a
175
+ > faded frame. A mesh whose `material` is not its own writable,
176
+ > configurable data property (read-only, an accessor, or inherited from
177
+ > its prototype) is drawn unfaded, and so is a frame whose
178
+ > renderer's `shadowMap.render` cannot take the hook (it goes on before
179
+ > any variant does). A deck that makes `shadowMap.render` read-only
180
+ > during a keyed frame has it put back (redefined) if it is still
181
+ > configurable; one it also makes non-configurable keeps the fade's
182
+ > hook, inert from then on: it only calls the pass it had. A deck
183
+ > setter on a mesh's `material` that throws when the material is put
184
+ > back holds that mesh, as below. Giving the meshes their materials back is total:
185
+ > each mesh on its own. A deck that redefines or locks its own mesh's
186
+ > `material` during a keyed render gets the best the fade can do without
187
+ > calling its getter: a data property made read-only but configurable
188
+ > is redefined with the deck's attributes and the original's value; an
189
+ > accessor with a setter has the original set through it once; anything
190
+ > else (read-only and not configurable, an accessor without a setter)
191
+ > keeps its variant, which reads and writes the original, and is tried
192
+ > again at every frame boundary while the fade lasts. Once the fade is
193
+ > dropped such a variant is inert: it keys and compiles exactly as its
194
+ > original, so later keyless frames draw the original's program. Its
195
+ > programs are not freed by a later `dispose()` of the original (that
196
+ > would take a listener on the shared material): on such a mesh only,
197
+ > each dispose and recompile leaves one program behind.
198
+ > Two more limits, inside the keyed world's own frame: a variant's
199
+ > properties live on its prototype (the forwarders), so deck code run
200
+ > during that frame (an LOD's `update`, a draw callback) that copies a
201
+ > mesh's material with a spread, `Object.keys` or own-property checks
202
+ > sees none of them, and whatever it writes from that copy differs from
203
+ > without the key (on a material shared with a keyless world, that world
204
+ > draws the write too). And a deck that defines a read-only, non-configurable
205
+ > property on one of three's own material prototypes, then shadows it on
206
+ > a material, makes a read of that property through a variant throw a
207
+ > `TypeError` (the forwarder is a Proxy, which must report the
208
+ > prototype's value). Neither happens in a world without the keys.
209
+
210
+ Without both keys nothing of this runs: the same materials, programs,
211
+ program keys, shader sources and draws as before
212
+ (scripts/test-orbit-shadow-fade.mjs, on three.js's own WebGLRenderer over
213
+ a context that draws nothing, also with a keyed and a keyless world
214
+ sharing materials). Under both keys the first faded frame compiles one
215
+ program per distinct lit program in view (a hitch, once), and each faded
216
+ frame walks the scene's visible objects and swaps each receiving lit
217
+ mesh's material twice, and three reads each variant's properties through
218
+ the forwarders. In node over a context that draws nothing, 500 receiving
219
+ meshes on 40 materials take about 2.7 ms a frame with the fade against
220
+ about 1.8 ms with near shadows alone (the JavaScript side only).
221
+
222
+ The depth range is the sun's own `near` and `far` along the light, measured
223
+ from the engine's shadow camera, which stands as far from the middle of the
224
+ view's sphere (taken along the light to the height of the sun's target) as
225
+ the sun does from its target. For the engine's sun (19.9 m from its target,
226
+ near 0.5, far 50) that is casters up to 19.4 m toward the sun and 30.1 m
227
+ away from it, from the ground under the middle of the view. It is what the
228
+ sun's own camera draws for a view round its target: there too a caster 25 m
229
+ up the light from a point on the ground is not drawn.
230
+
231
+ How it stays out of the scene's way (`engine3d/nearshadows.js` has the rule
232
+ and the code):
233
+ > The scene's sun, its shadow object, its shadow camera, its map and its
234
+ > target are never written by this mode. What the mode needs is its own
235
+ > objects, attached only for the duration of one renderer.render call
236
+ > inside try/finally. Outside that call the world is as main leaves it, so
237
+ > there is nothing to restore on a scene change, a throw, a dispose or a
238
+ > keyless frame.
239
+
240
+ Who the key is for:
241
+ > The key is for a scene whose deck leaves the renderer's shadow settings
242
+ > and the drawing of the world to the engine. A deck must not set the key if
243
+ > any of its code, in any scene played in the same world, changes
244
+ > renderer.shadowMap.type, .enabled, .autoUpdate or .needsUpdate after the
245
+ > world is made; calls renderer.render or the composer itself, inside or
246
+ > between the engine's frames; calls renderWorld from inside a frame; or
247
+ > gives the world's renderer to another world. In a deck that does, shadows
248
+ > may be drawn wrongly with the key, and three.js's shadow bookkeeping for
249
+ > the sun's own map (its filter, its size) may differ from a world that
250
+ > never had the key until the world is disposed. A deck that never sets the
251
+ > key is unaffected whatever it does.
252
+
253
+ (three.js keeps the shadow pass's state, the type it last drew with and the
254
+ frustum it culls by, inside the renderer, where the engine can neither read
255
+ it nor put it back. Nothing in the kits does any of the above after
256
+ `makeWorld3D`.) Nothing of the renderer's is ever written by the mode.
257
+ (With the orbit key as well, the far-edge fade below puts a hook on the
258
+ world renderer's `shadowMap.render` for the one render call, and takes
259
+ it off after. The opt-in still cache above also hooks that call.)
260
+
261
+ Within that, the mode draws a frame only when all of these hold; otherwise
262
+ the frame is drawn exactly as without the key. They are cheap protection,
263
+ looked at every frame, not promises about a deck outside the condition
264
+ above. After any `renderWorld` call returns, either the mode drew that
265
+ frame or nothing of the mode's is allocated: every way out of the mode (a
266
+ frame drawn plain for any term, a re-entry, a throw, a dispose) frees its
267
+ map at that moment:
268
+ 1. the scene now playing asked, with a finite distance above 0
269
+ (`runtime.nearShadowDistance`, read when the scene loads), the frame is
270
+ the player's (the scene and model editors give `renderWorld` no runtime),
271
+ and the world is not being disposed;
272
+ 2. `renderWorld` was not entered from inside another `renderWorld` of this
273
+ world that had anything of the mode's to do, keyed or not, and no frame
274
+ of this world has been entered that way before. The call inside is drawn
275
+ plain; the sun has its own shadow back before that call draws, and still
276
+ has it when the call returns, whatever the call did, disposing the world
277
+ included; the mode is off for this world from then until the world is
278
+ disposed (`world.nearShadows.off`); and the frame that was re-entered,
279
+ whose map is freed under it, may have wrong or missing shadows, that
280
+ once;
281
+ 3. read at the start of the frame, `renderer.shadowMap.type` is
282
+ `PCFSoftShadowMap` and `.enabled` and `.autoUpdate` are on, which is how
283
+ the engine makes the renderer; and the frame before was also a frame
284
+ with the key that found the same and was drawn to the end
285
+ (`world.nearShadows.lastType`). So the first frame with the key, after a
286
+ load or after any frame without it, is drawn plain, and three.js
287
+ allocates and configures the sun's own map as it would have; and so is
288
+ the frame after one that threw, and after one the mode drew that ended
289
+ with no map on the engine's shadow (three.js drew nothing: a lost
290
+ context). The engine's shadow never has a blur map;
291
+ 4. the sun (`world.sun`, the light whose bias the engine fits) is still a
292
+ child of the scene, is the first directional light there that casts, has
293
+ `castShadow` on, is visible and on the camera's layers, and its own
294
+ shadow is a directional light's, has `autoUpdate` on and has its map.
295
+ Looked at every frame: a sun removed or replaced means plain frames, in
296
+ which a replacement draws its own box as without the key;
297
+ 5. the camera is a perspective camera, and the sun's own box and map size
298
+ give a texel size: its shadow camera has zoom 1 and no view offset.
299
+
300
+ All of the mode's work in a `renderWorld` call (deciding the terms, fitting
301
+ the bias, allocating, swapping, rendering, leaving, disposing) happens
302
+ inside one outermost try/finally, counted on the world
303
+ (`world.nearShadows.depth`). A call that arrives while the count is up
304
+ draws plain, puts the mode off and makes nothing. The finally establishes
305
+ the postcondition itself: unless the mode drew this frame to the end, on a
306
+ world not disposed, with the mode not off and a map on its shadow, nothing
307
+ of the mode's is allocated and the sun has its own shadow. Its order is
308
+ what makes that hold through a `dispose` listener that throws: first the
309
+ sun gets its own shadow back (an assignment, which calls no one), then what
310
+ is freed is detached and only then disposed, and looked at again after the
311
+ callbacks; the count comes down in a finally of its own that nothing skips.
312
+ A world with no mode state playing a scene without the key does not enter
313
+ any of it: `renderWorld` runs its two statements (fit the bias, render)
314
+ with no counter and no try, as it always did.
315
+
316
+ On such a frame `renderWorld` fits the bias of the sun's own shadow as
317
+ always, puts the engine's shadow on the sun (`sun.shadow`), renders, and
318
+ puts the sun's own back in a `finally`; that assignment is the only write,
319
+ and it is undone only by the frame that made it (a frame that finds the
320
+ world disposed, its state replaced or itself re-entered touches nothing).
321
+ three.js keeps nothing per shadow object (the shadow pass and the light
322
+ uniforms read `light.shadow` afresh every render), so the next plain render
323
+ reads the sun's own as if nothing had happened. The engine's shadow
324
+ (`world.nearShadows.shadow`, a DirectionalLightShadow with its own camera,
325
+ map, matrix and frustum), each frame:
326
+ - looks along the sun's direction, from as far as the sun is from its
327
+ target, with the sun's own near and far, round the smallest sphere that
328
+ holds the camera's view out to `distance`: one size whichever way the
329
+ camera turns (it changes only with the canvas's shape or the camera's
330
+ lens). It sits a whole number of texels along each of its axes, so a
331
+ shadow's edge does not crawl as the camera moves. The light does not move;
332
+ - has texels exactly the size of the sun's own (the sun's box over its map
333
+ size, read each frame), so its box is `map size x texel` and it copies the
334
+ bias `fitShadowBias` fitted to the sun's own, with its intensity and
335
+ radius: 40 m on a portrait phone is a 710 x 888 map. Its map is never
336
+ larger than the sun's own in area (2048 x 2048) nor than the renderer's
337
+ largest texture on a side; a `distance` that would need more is drawn as
338
+ the largest that fits (about 100 m in portrait, 38 m at 32:9) rather than
339
+ with larger texels;
340
+ - hands three.js a frustum to cull casters with (`getFrustum`) that is its
341
+ box narrowed to the view's outline, out to `distance`, as the sun sees it,
342
+ pushed out by everything three.js's shader moves a shadow lookup by across
343
+ the light: the normal bias drawn with that frame (the lookup is made at
344
+ `position + normal * normalBias`) and four texels for the soft filter's
345
+ taps. The box is wider by the same. Every caster whose shadow
346
+ can land on something the view sees within `distance` is drawn into the
347
+ map; one whose shadow cannot is not. Without `cacheStill`, no
348
+ `castShadow` flag is changed and nothing is cached: every caster that
349
+ is drawn is drawn every frame, so a moving thing's shadow moves with it
350
+ as before.
351
+
352
+ A frame without the key drops what the mode holds, all but `off`;
353
+ `disposeWorld` drops it all. The engine's map (and a blur map, were there
354
+ one) is taken off its shadow before it is disposed, once.
355
+
356
+ What a deck that works on the sun sees under the key: the sun's own
357
+ `shadow.camera` box, `mapSize` and any `getFrustum` of its own are left as
358
+ they are and not used for drawing on the frames the mode draws (a sun whose
359
+ `shadow.autoUpdate` the deck turned off gets plain frames, term 4),
360
+ except that the box over the map size gives the texel size and `near`/`far`,
361
+ `bias`, `normalBias`, `intensity` and `radius` are copied each frame;
362
+ three.js does not draw the sun's own shadow on those frames, so its map and
363
+ its shadow camera's matrices stay as the last plain frame left them; a sun
364
+ moved or re-aimed is followed (its direction is read each frame). Without
365
+ the key such a deck works exactly as before. What differs on screen with
366
+ the key: shadows no longer end at the fixed box's edge, so a scene larger
367
+ than that box gains shadows where it had none; beyond `distance` from the
368
+ camera they thin out and, past the engine's box (which reaches somewhat
369
+ farther than `distance`), end, with a hard edge if the camera can see that
370
+ far (pick a distance past the ground the camera can see). Opt in when a
371
+ scene is wide enough that most of its casters are out of sight; a scene
372
+ that fits the view gains nothing.
@@ -0,0 +1,187 @@
1
+ # Scene keys: engine.skipEmptyGaitHints, skipUnchangedActors, dropEmptyParts, skipEmptyNodes
2
+
3
+ The physics-3d kit's CLAUDE.md Quick reference points here. The keys sit in
4
+ the `engine` object at a scene file's top level, beside `ground`.
5
+
6
+ - `"engine": { "skipEmptyGaitHints": true }` skips clock reads and hint
7
+ consumption when an actor node has none of `walkSpeedHint`, `walkTimeHint`,
8
+ or `walkHintAt`. It applies only in play, with model gait; the editor and
9
+ scenes without the key retain the original path. Hint-bearing nodes keep
10
+ their original freshness checks and one-frame consumption. Under this key,
11
+ node `userData` must be ordinary stored data, without accessors or Proxies.
12
+ - `"engine": { "skipUnchangedActors": true }` at the scene file's top level,
13
+ beside `ground`, asks the engine not to redo, every frame, work whose answer
14
+ cannot have changed. The terms:
15
+ > With the key absent, a scene runs the engine exactly as before. With the key
16
+ > present, each frame equals what the engine would have produced without it
17
+ > PROVIDED the scene's components are plain stored data (no accessors, Proxies,
18
+ > toJSON, custom iterators) and three.js objects under actors are changed only
19
+ > through position/rotation/quaternion/scale/visible/parenting. A scene that does
20
+ > not meet that is unsupported under the key and must not set it.
21
+
22
+ It is read when the scene loads, so it follows a scene switch, and a mounted
23
+ pack's scene decides for itself. What is skipped for an actor nothing has
24
+ touched: building the signatures that decide whether its mesh and its
25
+ physics body need rebuilding, recomputing its node's matrices, and sorting
26
+ the actor list. Behaviors run exactly as without the key. Each skipped piece
27
+ is skipped only after reading its inputs and finding them as they were, so
28
+ nothing has to be marked dirty: an actor still follows a change on the very
29
+ next frame -- a component's stored field written in place, a component
30
+ added, removed or replaced, a spawn or despawn, physics, the editor, the
31
+ network, its node posed from `scene.three`. Opt in when a scene is several
32
+ hundred actors that mostly stand still and frame time on a slow phone is
33
+ script, not drawing; a small scene gains nothing.
34
+ How it stays right when deck code runs in the middle of the engine's own
35
+ work (`engine3d/world3d.js` has the rule and the code):
36
+ > Fast-path state (snapshots, pass marks, cached signatures) is trusted only
37
+ > across a span in which no code outside the engine has run. A pass in which
38
+ > the engine calls out (any callback), is re-entered, or sees the scene
39
+ > change, finishes exactly as main would and leaves no fast-path state
40
+ > behind.
41
+
42
+ The engine moves a counter before it does anything, inside a pass over the
43
+ actors, that can run code that is not its own; it does not work out
44
+ afterwards whether something ran. The places, all of them:
45
+ `scene.three.scene.userData.groundHeight`, called while a walking model is
46
+ animated; and three.js listeners (`added`, `removed`, `childadded`,
47
+ `childremoved`, `dispose`) on the scene, a node, a geometry or a material,
48
+ told when a node is built, rebuilt or released, when the scene changes, when
49
+ the ground is dressed anew, and when an instanced mesh is replaced; and
50
+ `syncActors` called again from inside any of those. From that point the
51
+ pass does each actor the old way and writes nothing down, and when it ends,
52
+ or if it throws, everything written down before is dropped. So:
53
+ - a frame in which any actor's mesh is built, rebuilt or released costs what
54
+ it costs without the key, and the frame after it reads every actor once
55
+ more before skipping resumes;
56
+ - a scene with a `groundHeight` callback, or with `instanceModels` on, runs
57
+ every pass the old way and keeps only the matrix saving;
58
+ - the physics pass calls nothing outside the engine until its collision
59
+ callbacks, which come last;
60
+ - a component nested more than 32 levels deep is compared the old way every
61
+ frame.
62
+
63
+ What is written down lives in the world's own maps (`world.snapshots`,
64
+ `world.modelSigs`) and in the physics system's (`remembered`), never on a
65
+ node entry or a body entry, and is dropped by replacing or clearing those.
66
+ The one thing on a node, an ActorNode's `computedFrom`, is numbers only and
67
+ refers to no object.
68
+ A world being disposed never skips: `disposeWorld` drops what was written
69
+ down before it releases the nodes and again after their `dispose` listeners
70
+ have run, so a listener that syncs the world again leaves nothing.
71
+ - Within the terms, these are followed: any stored field of a Shape, Model,
72
+ Body or Transform changed, added, removed or reordered, at any depth; art
73
+ loading or being replaced; a model file, or a model it references, edited;
74
+ a node's, or any object under it's, position, rotation (angles or order),
75
+ quaternion, scale or visibility set; children added, removed, reordered,
76
+ or moved to another parent and back; a body's type changed through
77
+ `scene.physics3d.bodyOf`.
78
+ - Outside the terms the result is not promised. The engine does notice some
79
+ of it and then does the old work for that actor, as protection, not as a
80
+ guarantee to build on: a component with an accessor, a `toJSON` or a class
81
+ of its own found when it is first read; an object under a node with
82
+ `matrixAutoUpdate` off or an `updateMatrixWorld` of its own (a camera, a
83
+ skinned mesh); a world matrix written by hand; a transform changed, used
84
+ and put back between frames.
85
+ - It does not notice, among others: a `Proxy` in place of a component, of
86
+ `actor.components` or of the `sprites` / `files` tables; a getter on
87
+ `Transform`, on `Shape.solid`, or on `actor.components` itself; a stored
88
+ field redefined as a getter after the engine has read it; an object's
89
+ local `matrix` written by hand while its `matrixAutoUpdate` is on (set
90
+ `position` / `quaternion` / `scale` instead); three.js private fields
91
+ written directly (`rotation._order`, `quaternion._x`).
92
+ - `"engine": { "dropEmptyParts": true }` at the scene file's top level (the
93
+ same `engine` object) asks the engine to place models without the groups
94
+ that draw nothing. A placed model is a game build: its meshes are merged
95
+ into a few draw calls, but every part keeps its own three.js group, most of
96
+ them then empty, and three.js and the engine visit every object under the
97
+ scene on every frame. A town of a few hundred models is two thirds such
98
+ groups. The terms:
99
+ > With the key absent, a model is built and placed exactly as before: the
100
+ > same objects, the same shared build, the same node. With the key present,
101
+ > every object that is drawn (a mesh, its outline, anything that is not a
102
+ > plain group) is the same object with the same geometry, material and
103
+ > world matrix as without it, on every frame, and walks, `motion`, clips and
104
+ > glow play the same. What a deck must not rely on under the key is finding
105
+ > the group of a part that draws nothing unless that part is one that
106
+ > stays.
107
+
108
+ What goes: a group with nothing drawn on it or anywhere under it -- no
109
+ mesh, line, points, sprite, light or camera. That includes the group of a
110
+ part that IS drawn when its mesh was merged into a batch on the model's
111
+ root or on a moving part: the picture keeps the part, `modelParts` does
112
+ not. What always stays, with every group above it:
113
+ - a part marked `keep: true` (docs/pxmodel-format.md: "for a deck that
114
+ reaches for it by id"), with its own mesh as before;
115
+ - a part named `slot-...`. The format's docs let a deck "parent your own
116
+ parts to it", and nothing says that happens only in the model file, so a
117
+ slot is never dropped: a deck may hang a mesh on one at runtime and it is
118
+ drawn where it would be without the key;
119
+ - a part the walk moves (`legL`, `legR`, `armL`, `armR`, `torso`) or the
120
+ model's `motion`, gait or `clips` move, drawn or not, and every copy of
121
+ one;
122
+ - anything a kept part or slot holds that is not another part.
123
+
124
+ An actor whose model draws nothing at all (an invisible collider placing an
125
+ empty model) gets no rig group under its node: the node is there, with
126
+ `userData.modelParts` an empty Map and no children.
127
+ So under the key:
128
+ - `scene.three.nodes.get(id).node.userData.modelParts` holds only the parts
129
+ that stayed. `modelParts.get('door')` for a part that draws nothing and
130
+ is none of the above is `undefined`, where without the key it is an empty
131
+ group. To reach for an empty part as a locator (a muzzle, a hand), mark
132
+ it `keep: true` or name it `slot-...`; it then stands exactly where it
133
+ did.
134
+ - code that walks a node's tree counts fewer objects, and a node's first
135
+ child is its rig only when its model draws something.
136
+ - nothing else changes: which actors have nodes, `userData.actorId`, the
137
+ rig's `yOffset` and `scale`, physics, picking, shadows (casters are
138
+ culled by their own meshes' bounds), `instanceModels`.
139
+
140
+ It is read when the scene loads, as `skipUnchangedActors` is, and each
141
+ scene decides for itself: a node and a shared model build made for a scene
142
+ that asked are never used for one that did not, or the other way round (a
143
+ resident scene parked while another plays, a pack mounted in a town, a door
144
+ trip, a scene file reloaded with the key changed -- every node is then
145
+ built again). The scene editor and the play panel draw a scene through the
146
+ same engine, so both follow the scene's key; the editor selects actors, not
147
+ parts, and is not affected. The model editor and `npm run render` build a
148
+ model for themselves, with every part's group, whatever any scene says.
149
+ Opt in with `skipUnchangedActors` when a scene is hundreds of placed
150
+ models; a scene of a few gains nothing.
151
+ - `"engine": { "skipEmptyNodes": true }` at the scene file's top level
152
+ keeps an actor with no children on its three.js node outside the play scene.
153
+ Empty markers, anchors and triggers then cost no scene object. A missing or
154
+ invalid Model with no Shape is empty; a Model that builds a rig is not,
155
+ even if its rig draws nothing. With `dropEmptyParts`, a model reduced to no
156
+ rig is empty too. The key is read on load, and only exactly `true` opts in.
157
+ Without it, nodes, signatures and shared model caches are exactly as before.
158
+ A player whose scenes never ask creates no mode record, system or listeners.
159
+ The player arms the mode only
160
+ after a keyed scene has finished loading; syncs never arm it. The scene
161
+ editor always keeps its nodes.
162
+
163
+ `scene.three.nodes` keeps every entry and its usual Group/ActorNode, with
164
+ position, rotation and world matrix placed by the engine even while detached.
165
+ Move an empty actor through its Transform (or physics), not by writing the
166
+ detached node's position, quaternion, rotation or scale directly: those
167
+ writes are outside this key's contract and do not update its world matrix
168
+ until the node has a child and is attached again.
169
+ No transform properties or methods are wrapped. Adding a
170
+ child queues attachment at the next actor sync; removing its last child
171
+ queues detachment there too, after three.js event dispatch completes.
172
+ Build and child events queue classification for the next outermost sync;
173
+ listeners only mark dirty, and syncs inside event dispatch defer the queue.
174
+ Dispatch depth unwinds even if a listener throws. A load, reset or disposal
175
+ invalidating a pass aborts it before any further placement or attachment.
176
+ Settled frames scan no nodes.
177
+ Only detached empty nodes whose pose changes receive a matrix update; a
178
+ settled static empty actor needs none. Load/reset gives nodes back before
179
+ the next scene runs, leaving keyless sync on its original path.
180
+ Gaining or losing a Model/Shape follows the usual look rebuild, including
181
+ spawn, reload, resident scenes and `staticActors` (call `scene.touch` before
182
+ changing a static actor, as usual). A node deliberately hidden or reparented
183
+ by a consumer stays under that consumer's control. Low-tier bounds and
184
+ hiding, avatar parts and attachments keep using the same entries. Traversing
185
+ the play scene excludes empty actors; traverse `scene.three.nodes` to find
186
+ all actors. If the scene itself has a transform or a parent, nodes stay
187
+ attached so world-space reads retain that transform.