castle-web-cli 0.4.232 → 0.4.233

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 (355) hide show
  1. package/dist/agent-failures.d.ts +8 -0
  2. package/dist/agent-failures.js +19 -2
  3. package/dist/agent-prompts.d.ts +1 -1
  4. package/dist/agent-prompts.js +10 -3
  5. package/dist/agent.d.ts +64 -3
  6. package/dist/agent.js +170 -81
  7. package/dist/castle-host/host.d.ts +1 -0
  8. package/dist/castle-host/host.js +51 -3
  9. package/dist/castleJson.d.ts +4 -2
  10. package/dist/castleJson.js +2 -0
  11. package/dist/check.d.ts +3 -1
  12. package/dist/check.js +11 -1
  13. package/dist/devSessionStorage.js +47 -1
  14. package/dist/importPinMismatch.d.ts +22 -0
  15. package/dist/importPinMismatch.js +77 -0
  16. package/dist/importRegression.js +3 -15
  17. package/dist/imports.d.ts +10 -3
  18. package/dist/imports.js +88 -20
  19. package/dist/index.js +5 -4
  20. package/dist/init.js +1 -1
  21. package/dist/platformDoc.js +22 -0
  22. package/dist/routerFences.d.ts +5 -0
  23. package/dist/routerFences.js +12 -2
  24. package/dist/save-deck.d.ts +5 -0
  25. package/dist/save-deck.js +37 -4
  26. package/dist/serve.js +3 -0
  27. package/dist/shell/assets/{index-D2tWM896.js → index-BjOxR-lW.js} +4 -4
  28. package/dist/shell/assets/index-MVLfNYd9.css +1 -0
  29. package/dist/shell/index.html +2 -2
  30. package/dist/taskSteer.d.ts +13 -0
  31. package/dist/taskSteer.js +22 -2
  32. package/kits/base/castle.json +1 -1
  33. package/kits/base/package-lock.json +1 -1
  34. package/kits/base/sdk/README.md +79 -2
  35. package/kits/base/sdk/avatar.d.ts +6 -2
  36. package/kits/base/sdk/avatar.js +12 -4
  37. package/kits/base/sdk/castle.d.ts +1 -1
  38. package/kits/base/sdk/commands.d.ts +14 -0
  39. package/kits/base/sdk/hub.d.ts +6 -2
  40. package/kits/base/sdk/hub.js +13 -0
  41. package/kits/base/sdk/multiplayer.js +17 -1
  42. package/kits/base/sdk/save.js +2 -1
  43. package/kits/base/sdk/server/hub.d.ts +87 -0
  44. package/kits/base/sdk/server/hub.js +70 -0
  45. package/kits/base/sdk/server/platformHandle.d.ts +31 -1
  46. package/kits/base/sdk/server/storage.d.ts +13 -0
  47. package/kits/base/sdk/server/storage.js +46 -0
  48. package/kits/base/sdk/server/wrapper.d.ts +36 -5
  49. package/kits/base/sdk/server/wrapper.js +83 -8
  50. package/kits/hub-game/CLAUDE.md +329 -11
  51. package/kits/hub-game/blueprints/avatar-10.scene +28 -0
  52. package/kits/hub-game/blueprints/avatar-11.scene +28 -0
  53. package/kits/hub-game/blueprints/avatar-12.scene +28 -0
  54. package/kits/hub-game/blueprints/avatar-13.scene +28 -0
  55. package/kits/hub-game/blueprints/avatar-14.scene +28 -0
  56. package/kits/hub-game/blueprints/avatar-15.scene +28 -0
  57. package/kits/hub-game/blueprints/avatar-4.scene +28 -0
  58. package/kits/hub-game/blueprints/avatar-5.scene +28 -0
  59. package/kits/hub-game/blueprints/avatar-6.scene +28 -0
  60. package/kits/hub-game/blueprints/avatar-7.scene +28 -0
  61. package/kits/hub-game/blueprints/avatar-8.scene +28 -0
  62. package/kits/hub-game/blueprints/avatar-9.scene +28 -0
  63. package/kits/hub-game/code/client/actorBudget.js +47 -0
  64. package/kits/hub-game/code/client/attention.js +11 -2
  65. package/kits/hub-game/code/client/avatar.js +309 -35
  66. package/kits/hub-game/code/client/avatarCap.js +228 -0
  67. package/kits/hub-game/code/client/avatarColors.js +70 -0
  68. package/kits/hub-game/code/client/avatarFaces.js +21 -0
  69. package/kits/hub-game/code/client/avatarShare.js +251 -0
  70. package/kits/hub-game/code/client/ballot.js +467 -0
  71. package/kits/hub-game/code/client/build.js +22 -0
  72. package/kits/hub-game/code/client/chrome.js +1144 -50
  73. package/kits/hub-game/code/client/companion.js +716 -0
  74. package/kits/hub-game/code/client/companionDress.js +99 -0
  75. package/kits/hub-game/code/client/decor.js +509 -0
  76. package/kits/hub-game/code/client/earned.js +131 -0
  77. package/kits/hub-game/code/client/emoteBubble.js +75 -0
  78. package/kits/hub-game/code/client/grab.js +339 -20
  79. package/kits/hub-game/code/client/hookLayer.js +299 -13
  80. package/kits/hub-game/code/client/idle.js +163 -22
  81. package/kits/hub-game/code/client/interestCap.js +81 -0
  82. package/kits/hub-game/code/client/keys.js +36 -0
  83. package/kits/hub-game/code/client/labelsNear.js +205 -0
  84. package/kits/hub-game/code/client/menuIcons.js +34 -0
  85. package/kits/hub-game/code/client/pack.js +6 -2
  86. package/kits/hub-game/code/client/packFormat.js +3 -3
  87. package/kits/hub-game/code/client/rehello.js +167 -0
  88. package/kits/hub-game/code/client/shot.js +92 -0
  89. package/kits/hub-game/code/client/sound.js +63 -8
  90. package/kits/hub-game/code/client/soundscape.js +1151 -0
  91. package/kits/hub-game/code/client/soundscapeActions.js +99 -0
  92. package/kits/hub-game/code/client/soundscapeAmbience.js +453 -0
  93. package/kits/hub-game/code/client/soundscapeBaked.js +143 -0
  94. package/kits/hub-game/code/client/soundscapeBusker.js +217 -0
  95. package/kits/hub-game/code/client/soundscapeCourt.js +200 -0
  96. package/kits/hub-game/code/client/soundscapeCrowd.js +331 -0
  97. package/kits/hub-game/code/client/soundscapeCues.js +362 -0
  98. package/kits/hub-game/code/client/soundscapeMap.js +181 -0
  99. package/kits/hub-game/code/client/soundscapeMarket.js +176 -0
  100. package/kits/hub-game/code/client/soundscapeMusic.js +126 -0
  101. package/kits/hub-game/code/client/soundscapeMusicEngine.js +460 -0
  102. package/kits/hub-game/code/client/soundscapeSimlish.js +737 -0
  103. package/kits/hub-game/code/client/soundscapeSongs.js +127 -0
  104. package/kits/hub-game/code/client/soundscapeSongsRound3.js +63 -0
  105. package/kits/hub-game/code/client/soundscapeSynthesis.js +168 -0
  106. package/kits/hub-game/code/client/soundscapeUi.js +211 -0
  107. package/kits/hub-game/code/client/soundscapeVoice.js +1209 -0
  108. package/kits/hub-game/code/client/soundscapeWaves.js +206 -0
  109. package/kits/hub-game/code/client/spin.js +101 -0
  110. package/kits/hub-game/code/client/state.js +109 -1
  111. package/kits/hub-game/code/client/stuck.js +259 -0
  112. package/kits/hub-game/code/client/talk.js +538 -47
  113. package/kits/hub-game/code/client/tiers.js +516 -27
  114. package/kits/hub-game/code/client/toastBand.js +37 -0
  115. package/kits/hub-game/code/client/together.js +32 -0
  116. package/kits/hub-game/code/client/visibility.js +43 -0
  117. package/kits/hub-game/code/client/wear.js +461 -170
  118. package/kits/hub-game/code/client/yours.js +199 -0
  119. package/kits/hub-game/code/companionSpec.js +45 -0
  120. package/kits/hub-game/code/privateText.js +7 -0
  121. package/kits/hub-game/code/server/actions.js +133 -0
  122. package/kits/hub-game/code/server/actors.js +9 -1
  123. package/kits/hub-game/code/server/ask.js +155 -0
  124. package/kits/hub-game/code/server/ballot.js +539 -0
  125. package/kits/hub-game/code/server/cells.js +100 -0
  126. package/kits/hub-game/code/server/companion.js +82 -0
  127. package/kits/hub-game/code/server/cues.js +70 -0
  128. package/kits/hub-game/code/server/decor.js +269 -0
  129. package/kits/hub-game/code/server/earned.js +461 -0
  130. package/kits/hub-game/code/server/friendBests.js +166 -0
  131. package/kits/hub-game/code/server/friendsAmong.js +232 -0
  132. package/kits/hub-game/code/server/history.js +5 -0
  133. package/kits/hub-game/code/server/hub.js +1254 -50
  134. package/kits/hub-game/code/server/idle.js +30 -11
  135. package/kits/hub-game/code/server/index.js +2 -2
  136. package/kits/hub-game/code/server/labels.js +28 -2
  137. package/kits/hub-game/code/server/manifest.js +378 -7
  138. package/kits/hub-game/code/server/menu.js +133 -0
  139. package/kits/hub-game/code/server/npcs.js +830 -80
  140. package/kits/hub-game/code/server/party.js +2 -2
  141. package/kits/hub-game/code/server/players.js +22 -0
  142. package/kits/hub-game/code/server/shot.js +110 -0
  143. package/kits/hub-game/code/server/standing.js +124 -0
  144. package/kits/hub-game/code/server/vis.js +113 -0
  145. package/kits/hub-game/code/server/wear.js +12 -0
  146. package/kits/hub-game/code/server/yours.js +59 -0
  147. package/kits/hub-game/code/shared/cues.js +9 -0
  148. package/kits/hub-game/code/shared/decor.js +41 -0
  149. package/kits/hub-game/code/shared/shot.js +19 -0
  150. package/kits/hub-game/code/shared/spin.js +57 -0
  151. package/kits/hub-game/code/systems/hub.js +845 -95
  152. package/kits/hub-game/docs/content-pack.md +1 -1
  153. package/kits/hub-game/docs/contract.md +2244 -61
  154. package/kits/hub-game/docs/home-pieces.md +64 -0
  155. package/kits/hub-game/models/avatar-10.pxmodel +28 -0
  156. package/kits/hub-game/models/avatar-11.pxmodel +28 -0
  157. package/kits/hub-game/models/avatar-12.pxmodel +27 -0
  158. package/kits/hub-game/models/avatar-13.pxmodel +24 -0
  159. package/kits/hub-game/models/avatar-14.pxmodel +29 -0
  160. package/kits/hub-game/models/avatar-15.pxmodel +24 -0
  161. package/kits/hub-game/models/avatar-4.pxmodel +29 -0
  162. package/kits/hub-game/models/avatar-5.pxmodel +27 -0
  163. package/kits/hub-game/models/avatar-6.pxmodel +26 -0
  164. package/kits/hub-game/models/avatar-7.pxmodel +25 -0
  165. package/kits/hub-game/models/avatar-8.pxmodel +24 -0
  166. package/kits/hub-game/models/avatar-9.pxmodel +30 -0
  167. package/kits/hub-game/models/earned/badge-round.pxmodel +100 -0
  168. package/kits/hub-game/models/earned/badge-shield.pxmodel +117 -0
  169. package/kits/hub-game/models/earned/badge-star.pxmodel +87 -0
  170. package/kits/hub-game/models/earned/belt-plain.pxmodel +72 -0
  171. package/kits/hub-game/models/earned/held-ball.pxmodel +43 -0
  172. package/kits/hub-game/models/earned/held-lantern.pxmodel +85 -0
  173. package/kits/hub-game/models/earned/held-net.pxmodel +57 -0
  174. package/kits/hub-game/models/earned/held-trophy.pxmodel +109 -0
  175. package/kits/hub-game/models/earned/pin-round.pxmodel +62 -0
  176. package/kits/hub-game/models/earned/sash-plain.pxmodel +66 -0
  177. package/kits/hub-game/models/earned/square/belt-plain.pxmodel +104 -0
  178. package/kits/hub-game/models/earned/square/sash-plain.pxmodel +98 -0
  179. package/kits/hub-game/models/hats/bat-clip.pxmodel +206 -0
  180. package/kits/hub-game/models/hats/beekeeper.pxmodel +149 -0
  181. package/kits/hub-game/models/hats/cap.pxmodel +162 -0
  182. package/kits/hub-game/models/hats/captain.pxmodel +178 -0
  183. package/kits/hub-game/models/hats/crooked-top.pxmodel +172 -0
  184. package/kits/hub-game/models/hats/flower-crown.pxmodel +451 -0
  185. package/kits/hub-game/models/hats/foam-crown.pxmodel +179 -0
  186. package/kits/hub-game/models/hats/lantern.pxmodel +230 -0
  187. package/kits/hub-game/models/hats/laurel.pxmodel +533 -0
  188. package/kits/hub-game/models/hats/lighthouse.pxmodel +96 -0
  189. package/kits/hub-game/models/hats/sailor.pxmodel +141 -0
  190. package/kits/hub-game/models/hats/souwester.pxmodel +131 -0
  191. package/kits/hub-game/models/hats/straw.pxmodel +139 -0
  192. package/kits/hub-game/models/hats/sunflower.pxmodel +406 -0
  193. package/kits/hub-game/models/hats/sweatband.pxmodel +112 -0
  194. package/kits/hub-game/models/hats/witch.pxmodel +147 -0
  195. package/kits/hub-game/package-lock.json +2 -0
  196. package/kits/hub-game/package.json +2 -1
  197. package/kits/hub-game/scripts/check.mjs +78 -11
  198. package/kits/hub-game/scripts/companion-follower-wire.json +1 -0
  199. package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +121 -0
  200. package/kits/hub-game/scripts/fixtures/decor-keyless.json +293 -0
  201. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +23 -0
  202. package/kits/hub-game/scripts/fixtures/fake-dom.mjs +107 -0
  203. package/kits/hub-game/scripts/fixtures/interest-legacy.json +385 -0
  204. package/kits/hub-game/scripts/fixtures/npc-notes-v1.77.jsonl +4 -0
  205. package/kits/hub-game/scripts/fixtures/vis-shared-wire.json +1 -0
  206. package/kits/hub-game/scripts/gen-avatars.mjs +933 -16
  207. package/kits/hub-game/scripts/gen-earned.mjs +285 -0
  208. package/kits/hub-game/scripts/gen-hats.mjs +827 -0
  209. package/kits/hub-game/scripts/grab.before-orbit.mjs +400 -0
  210. package/kits/hub-game/scripts/soundscape-wave-analysis.mjs +125 -0
  211. package/kits/hub-game/scripts/test-actions-client.mjs +488 -0
  212. package/kits/hub-game/scripts/test-actions.mjs +298 -0
  213. package/kits/hub-game/scripts/test-actor-budget.mjs +44 -0
  214. package/kits/hub-game/scripts/test-actors.mjs +19 -17
  215. package/kits/hub-game/scripts/test-ask-client.mjs +358 -0
  216. package/kits/hub-game/scripts/test-ask.mjs +269 -0
  217. package/kits/hub-game/scripts/test-attention.mjs +10 -1
  218. package/kits/hub-game/scripts/test-avatar-cap.mjs +379 -0
  219. package/kits/hub-game/scripts/test-avatar-colors.mjs +72 -0
  220. package/kits/hub-game/scripts/test-avatar-models.mjs +181 -0
  221. package/kits/hub-game/scripts/test-avatar-share.mjs +318 -0
  222. package/kits/hub-game/scripts/test-avatar-wire.mjs +753 -0
  223. package/kits/hub-game/scripts/test-avatar.mjs +540 -7
  224. package/kits/hub-game/scripts/test-ballot.mjs +1001 -0
  225. package/kits/hub-game/scripts/test-build.mjs +31 -0
  226. package/kits/hub-game/scripts/test-cells.mjs +71 -0
  227. package/kits/hub-game/scripts/test-chat.mjs +662 -0
  228. package/kits/hub-game/scripts/test-classic.mjs +2 -0
  229. package/kits/hub-game/scripts/test-companion-chat.mjs +198 -0
  230. package/kits/hub-game/scripts/test-companion-client.mjs +1167 -0
  231. package/kits/hub-game/scripts/test-companion.mjs +259 -0
  232. package/kits/hub-game/scripts/test-decor-client.mjs +303 -0
  233. package/kits/hub-game/scripts/test-decor.mjs +457 -0
  234. package/kits/hub-game/scripts/test-earned-client.mjs +459 -0
  235. package/kits/hub-game/scripts/test-earned.mjs +1194 -0
  236. package/kits/hub-game/scripts/test-emote-bubble.mjs +110 -0
  237. package/kits/hub-game/scripts/test-friend-bests.mjs +435 -0
  238. package/kits/hub-game/scripts/test-grab-orbit.mjs +918 -0
  239. package/kits/hub-game/scripts/test-grab.mjs +7 -0
  240. package/kits/hub-game/scripts/test-hats.mjs +422 -168
  241. package/kits/hub-game/scripts/test-hub-leaving.mjs +203 -0
  242. package/kits/hub-game/scripts/test-hub-ops.mjs +439 -2
  243. package/kits/hub-game/scripts/test-hub-trip.mjs +716 -2
  244. package/kits/hub-game/scripts/test-hud-clear.mjs +328 -4
  245. package/kits/hub-game/scripts/test-idle.mjs +361 -1
  246. package/kits/hub-game/scripts/test-interest-cap.mjs +36 -0
  247. package/kits/hub-game/scripts/test-interest-cells.mjs +493 -0
  248. package/kits/hub-game/scripts/test-interest-client.mjs +118 -0
  249. package/kits/hub-game/scripts/test-keys.mjs +46 -1
  250. package/kits/hub-game/scripts/test-labels.mjs +596 -0
  251. package/kits/hub-game/scripts/test-manifest.mjs +207 -0
  252. package/kits/hub-game/scripts/test-menu-client.mjs +480 -0
  253. package/kits/hub-game/scripts/test-menu.mjs +296 -0
  254. package/kits/hub-game/scripts/test-npcs.mjs +1718 -12
  255. package/kits/hub-game/scripts/test-object-entry.mjs +76 -0
  256. package/kits/hub-game/scripts/test-pack.mjs +7 -0
  257. package/kits/hub-game/scripts/test-picker.mjs +314 -0
  258. package/kits/hub-game/scripts/test-rehello.mjs +1039 -0
  259. package/kits/hub-game/scripts/test-relations-among.mjs +222 -0
  260. package/kits/hub-game/scripts/test-relations-refresh.mjs +188 -0
  261. package/kits/hub-game/scripts/test-shot.mjs +756 -0
  262. package/kits/hub-game/scripts/test-soundscape.mjs +5432 -0
  263. package/kits/hub-game/scripts/test-spin.mjs +314 -0
  264. package/kits/hub-game/scripts/test-standing.mjs +416 -0
  265. package/kits/hub-game/scripts/test-stuck.mjs +1903 -0
  266. package/kits/hub-game/scripts/test-tier-cells.mjs +706 -0
  267. package/kits/hub-game/scripts/test-tiers-render.mjs +339 -0
  268. package/kits/hub-game/scripts/test-tiers.mjs +477 -2
  269. package/kits/hub-game/scripts/test-toast-band.mjs +61 -0
  270. package/kits/hub-game/scripts/test-try-on.mjs +22 -22
  271. package/kits/hub-game/scripts/test-vis.mjs +343 -0
  272. package/kits/hub-game/scripts/test-visibility.mjs +134 -0
  273. package/kits/hub-game/scripts/test-yours-chrome.mjs +166 -0
  274. package/kits/hub-game/scripts/test-yours.mjs +372 -0
  275. package/kits/multiplayer-3d/CLAUDE.md +50 -0
  276. package/kits/multiplayer-3d/castle.json +5 -5
  277. package/kits/multiplayer-3d/code/client/avatars.js +7 -0
  278. package/kits/multiplayer-3d/code/client/gait.js +65 -0
  279. package/kits/multiplayer-3d/code/client/nameTags.js +59 -4
  280. package/kits/multiplayer-3d/code/options.js +5 -0
  281. package/kits/multiplayer-3d/code/server/ownership.js +10 -2
  282. package/kits/multiplayer-3d/code/server/sceneBodies.js +12 -0
  283. package/kits/multiplayer-3d/code/server/world.js +7 -0
  284. package/kits/multiplayer-3d/code/systems/multiplayer.js +74 -4
  285. package/kits/multiplayer-3d/package.json +2 -1
  286. package/kits/multiplayer-3d/scripts/fixtures/README.md +11 -0
  287. package/kits/multiplayer-3d/scripts/fixtures/ownership-legacy.json +2 -0
  288. package/kits/multiplayer-3d/scripts/ownership-harness.mjs +102 -0
  289. package/kits/multiplayer-3d/scripts/ownership-loader.mjs +46 -0
  290. package/kits/multiplayer-3d/scripts/ownership-worker.mjs +15 -0
  291. package/kits/multiplayer-3d/scripts/record-ownership-session.mjs +98 -0
  292. package/kits/multiplayer-3d/scripts/test-eligible-claims.mjs +167 -0
  293. package/kits/multiplayer-3d/scripts/test-own-name-tag.mjs +247 -0
  294. package/kits/physics-2d/CLAUDE.md +9 -0
  295. package/kits/physics-2d/castle.json +2 -2
  296. package/kits/physics-2d/engine/scene.js +253 -1
  297. package/kits/physics-2d/engine/skyKey.js +129 -0
  298. package/kits/physics-2d/engine/stillClock.js +106 -0
  299. package/kits/physics-2d/engine/updateBudget.js +21 -0
  300. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +326 -1
  301. package/kits/physics-3d/CLAUDE.md +1169 -30
  302. package/kits/physics-3d/behaviors/Player.jsx +629 -72
  303. package/kits/physics-3d/castle.json +3 -3
  304. package/kits/physics-3d/docs/pxmodel-format.md +8 -0
  305. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +69 -13
  306. package/kits/physics-3d/engine3d/actornode.js +86 -0
  307. package/kits/physics-3d/engine3d/animationBudget.js +23 -0
  308. package/kits/physics-3d/engine3d/editorWorld.js +6 -0
  309. package/kits/physics-3d/engine3d/emptynodes.js +232 -0
  310. package/kits/physics-3d/engine3d/framecap.js +96 -0
  311. package/kits/physics-3d/engine3d/gait.js +118 -0
  312. package/kits/physics-3d/engine3d/kithooks.js +47 -0
  313. package/kits/physics-3d/engine3d/look.js +507 -48
  314. package/kits/physics-3d/engine3d/lookbake.js +208 -0
  315. package/kits/physics-3d/engine3d/materialpresets.js +2 -0
  316. package/kits/physics-3d/engine3d/motion.js +39 -10
  317. package/kits/physics-3d/engine3d/nearshadows.js +37 -19
  318. package/kits/physics-3d/engine3d/optimize.js +9 -5
  319. package/kits/physics-3d/engine3d/orbitinput.js +487 -9
  320. package/kits/physics-3d/engine3d/orbitlens.js +48 -0
  321. package/kits/physics-3d/engine3d/ownmodel.js +213 -0
  322. package/kits/physics-3d/engine3d/pxmodel.js +42 -11
  323. package/kits/physics-3d/engine3d/shadowfade.js +882 -0
  324. package/kits/physics-3d/engine3d/sky.js +547 -0
  325. package/kits/physics-3d/engine3d/skylife.js +306 -0
  326. package/kits/physics-3d/engine3d/unchanged.js +11 -0
  327. package/kits/physics-3d/engine3d/viewrange.js +52 -0
  328. package/kits/physics-3d/engine3d/world3d.js +796 -69
  329. package/kits/physics-3d/main.jsx +5 -0
  330. package/kits/physics-3d/package.json +1 -1
  331. package/kits/physics-3d/scripts/look-baseline.mjs +155 -0
  332. package/kits/physics-3d/scripts/test-camera-orbit.mjs +2563 -80
  333. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +1 -1
  334. package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +435 -0
  335. package/kits/physics-3d/scripts/test-frame-cap.mjs +452 -0
  336. package/kits/physics-3d/scripts/test-gait.mjs +387 -0
  337. package/kits/physics-3d/scripts/test-look-bake.mjs +1056 -0
  338. package/kits/physics-3d/scripts/test-model-parse-cache.mjs +92 -0
  339. package/kits/physics-3d/scripts/test-near-shadows.mjs +3 -0
  340. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +1920 -0
  341. package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +545 -0
  342. package/kits/physics-3d/scripts/test-orbit-shot.mjs +583 -0
  343. package/kits/physics-3d/scripts/test-orbit-view.mjs +230 -0
  344. package/kits/physics-3d/scripts/test-skip-empty-nodes.mjs +845 -0
  345. package/kits/physics-3d/scripts/test-sky.mjs +2470 -0
  346. package/kits/physics-3d/scripts/test-static-actors.mjs +8 -1
  347. package/kits/physics-3d/scripts/test-static-scenery.mjs +2171 -0
  348. package/kits/physics-3d/scripts/test-steady-hover.mjs +2 -0
  349. package/kits/physics-3d/scripts/test-view-range.mjs +260 -0
  350. package/kits/physics-3d/systems/physics3d.js +383 -6
  351. package/kits/real-time/castle.json +2 -2
  352. package/kits/real-time/code/server/gameHooks.js +7 -0
  353. package/kits/real-time/code/server/session.js +97 -19
  354. package/package.json +2 -2
  355. package/dist/shell/assets/index-Cf61cNfT.css +0 -1
@@ -50,16 +50,16 @@
50
50
  "imports": {
51
51
  "castle.physics-2d": {
52
52
  "deckId": "ckRZGFW4iPrx",
53
- "version": "2026-10-05T08:03:43.791Z"
53
+ "version": "2026-10-08T15:09:06.913Z"
54
54
  },
55
55
  "castle.base": {
56
56
  "deckId": "yRcmH4_aYllE",
57
- "version": "2026-10-04T22:42:38.248Z"
57
+ "version": "2026-10-08T10:40:20.107Z"
58
58
  }
59
59
  },
60
60
  "main": "main.jsx",
61
61
  "autoUpdateWhenImported": true,
62
62
  "deckId": "JH0SclbPVP0y",
63
63
  "cardId": "eXfAaUdbSU5A",
64
- "publishedVersion": "2026-10-05T08:03:58.819Z"
64
+ "publishedVersion": "2026-10-08T15:11:19.728Z"
65
65
  }
@@ -870,6 +870,14 @@ drawn apart from the rest (see Cost), so move the few parts that matter.
870
870
 
871
871
  ### Gaits
872
872
 
873
+ Set `"gait": "model"` at the top level of the deck's own `castle.json` to
874
+ match walk cadence to world-space leg length (including model/actor scale).
875
+ Without it, the fixed gait is unchanged. Missing legs fall back to 45% of
876
+ visible model height, then the fixed constants if no height is measurable.
877
+ Multiplayer-3d supplies remote cadence from network tracks; local motion,
878
+ air poses and turn lean still follow position. Long paused frames advance
879
+ at most 0.1 seconds of model gait.
880
+
873
881
  These part ids animate from the actor's observed motion (anything that
874
882
  moves, walks):
875
883
 
@@ -12,7 +12,10 @@ import {
12
12
  disposeWorld,
13
13
  updatePhysicsDebug,
14
14
  } from './world3d';
15
+ import { prepareEmptyNodes, loadEmptyScene } from './emptynodes';
15
16
  import { attachOrbitInput } from './orbitinput';
17
+ import { renderHidingOwnModel } from './ownmodel';
18
+ import { makeFrameClock, makeInputLatch, nextFrame, updateLending } from './framecap';
16
19
 
17
20
  export function Scene3DPlayer({
18
21
  sceneData,
@@ -34,6 +37,9 @@ export function Scene3DPlayer({
34
37
  const runtime = makeScene(sceneData, behaviorClasses, sprites, files, scenePath);
35
38
  const world = makeWorld3D(canvas);
36
39
  runtime.three = world;
40
+ if (runtime.skipsEmptyNodes) prepareEmptyNodes(world, runtime);
41
+ // The first load precedes world creation; later loads initialize at the latch.
42
+ if (runtime.cameraControl === 'orbit') world.ownModelWith ??= new Set();
37
43
  runtime.hud = {};
38
44
  // Scene-independent state: survives `loadFromFile` (the scene data is
39
45
  // replaced, the runtime instance is not). Player score/inventory and the
@@ -44,14 +50,16 @@ export function Scene3DPlayer({
44
50
  // deck's content, mounted as data); a caller checks before asking.
45
51
  runtime.mountsContent = true;
46
52
 
47
- const detachInput = attachInput(canvas, runtime, world);
53
+ // What went down between capped frames, for the next one that runs.
54
+ const latch = makeInputLatch();
55
+ const detachInput = attachInput(canvas, runtime, world, latch);
48
56
  const stopResize = attachResize(canvas, world);
49
57
  const onLoopError = (err) => {
50
58
  console.error(err);
51
59
  setError(err);
52
60
  };
53
61
  const hudRefs = { score: scoreRef, look: lookRef };
54
- const stopLoop = startLoop(runtime, world, sprites, hudRefs, onFirstFrame, onLoopError);
62
+ const stopLoop = startLoop(runtime, world, sprites, hudRefs, onFirstFrame, onLoopError, latch);
55
63
  return () => {
56
64
  stopLoop();
57
65
  stopResize();
@@ -90,15 +98,25 @@ export function Scene3DPlayer({
90
98
  );
91
99
  }
92
100
 
93
- function attachInput(canvas, runtime, world) {
101
+ function attachInput(canvas, runtime, world, latch) {
94
102
  const onKeyDown = (event) => {
95
103
  // Space is gameplay (jump); keep it from scrolling the page.
96
104
  if (event.code === 'Space' && event.target === canvas) event.preventDefault();
97
105
  if (event.code === 'KeyP' && !event.repeat) {
98
106
  world.debugLines.visible = !world.debugLines.visible;
99
107
  }
108
+ if (runtime.cameraControl === 'orbit' && event.key === 'Shift' && !event.repeat &&
109
+ !event.target?.isContentEditable && !event.target?.closest?.('input, textarea, select')) {
110
+ runtime.orbitInput().shiftLock.toggle();
111
+ }
100
112
  runtime.keys.add(event.code);
101
113
  runtime.keys.add(event.key);
114
+ // A key's auto-repeat is not a new press: it is held, and a frame that
115
+ // runs sees it held.
116
+ if (runtime.maxFps > 0 && !event.repeat) {
117
+ latch.keys.add(event.code);
118
+ latch.keys.add(event.key);
119
+ }
102
120
  };
103
121
  const onKeyUp = (event) => {
104
122
  runtime.keys.delete(event.code);
@@ -138,7 +156,7 @@ function attachInput(canvas, runtime, world) {
138
156
  // A scene that set `"engine": { "camera": { "control": "orbit" } }` beside
139
157
  // `"follow": "rigid"`: a pointer that goes down in it is orbitinput.js's
140
158
  // from then until it lifts (or a scene loads). It is made the first time
141
- // a pointer goes down under the key or a Player runs under it
159
+ // a pointer goes down under the key, Shift is pressed there, or a Player runs under it
142
160
  // (`runtime.orbitInput()`), never in a runtime that does not meet the key.
143
161
  // Without the key each handler below reads one property and goes on as it
144
162
  // always did.
@@ -151,7 +169,10 @@ function attachInput(canvas, runtime, world) {
151
169
  () => {
152
170
  jumpPending = true;
153
171
  },
154
- { stickRadius: STICK_RADIUS_PX, tapSlop: TAP_SLOP_PX, tapMs: TAP_MS }
172
+ { stickRadius: STICK_RADIUS_PX, tapSlop: TAP_SLOP_PX, tapMs: TAP_MS },
173
+ // A pointer that came up unseen while a lock of the orbit input's
174
+ // was on: a pointercancel for it, through the handler below.
175
+ (event) => onPointerUp(event)
155
176
  ));
156
177
  const onPointerDown = (event) => {
157
178
  if (runtime.cameraControl === 'orbit') {
@@ -171,10 +192,19 @@ function attachInput(canvas, runtime, world) {
171
192
  time: performance.now(),
172
193
  moved: false,
173
194
  });
195
+ // A runtime that has met the key: the orbit input gives this pointer
196
+ // its capture back if a lock of its own ends while it is down.
197
+ orbit?.pointer(event);
174
198
  canvas.setPointerCapture(event.pointerId);
175
199
  };
176
200
  const onPointerMove = (event) => {
177
- if (orbit?.busy && orbit.move(event)) return;
201
+ if (orbit?.active && orbit.move(event)) {
202
+ // The orbit input writes its stick into `move` too: under a cap it is
203
+ // lent like the stick below, so a drag that ends between two capped
204
+ // frames is still seen.
205
+ if (runtime.maxFps > 0 && move.active) latch.stick = { x: move.x, y: move.y };
206
+ return;
207
+ }
178
208
  const p = pointers.get(event.pointerId);
179
209
  if (!p) return;
180
210
  const dx = event.clientX - p.x;
@@ -191,9 +221,11 @@ function attachInput(canvas, runtime, world) {
191
221
  move.active = true;
192
222
  move.x = nx * scale;
193
223
  move.y = ny * scale;
224
+ if (runtime.maxFps > 0) latch.stick = { x: move.x, y: move.y };
194
225
  };
195
226
  const onPointerUp = (event) => {
196
227
  if (orbit?.busy && orbit.up(event)) return;
228
+ orbit?.pointer(event);
197
229
  const p = pointers.get(event.pointerId);
198
230
  pointers.delete(event.pointerId);
199
231
  if (stickId === event.pointerId) clearStick();
@@ -226,27 +258,51 @@ function attachResize(canvas, world) {
226
258
  return () => observer.disconnect();
227
259
  }
228
260
 
229
- function startLoop(runtime, world, sprites, hudRefs, onFirstFrame, onError) {
261
+ function startLoop(runtime, world, sprites, hudRefs, onFirstFrame, onError, latch) {
230
262
  let raf = 0;
231
- let previousTime = performance.now();
263
+ const clock = makeFrameClock(performance.now());
232
264
  let firstFrameSignaled = false;
233
265
  const tick = (now) => {
234
- const dt = Math.min(0.033, (now - previousTime) / 1000);
235
- previousTime = now;
266
+ // A scene that set `engine.maxFps` skips an animation frame that comes
267
+ // too soon after the last frame that ran (`framecap.js`); without it
268
+ // every animation frame runs, handed what it always was.
269
+ const maxFps = runtime.maxFps;
270
+ const dt = nextFrame(clock, now, maxFps);
271
+ if (dt === null) {
272
+ raf = requestAnimationFrame(tick);
273
+ return;
274
+ }
236
275
  try {
237
- runtime.update(dt);
276
+ // A capped frame also sees what went down while frames were skipped.
277
+ if (maxFps > 0) updateLending(runtime, latch, dt);
278
+ else {
279
+ // Nothing noted under a cap outlives it: a frame without one drops it.
280
+ if (latch.keys.size > 0 || latch.stick) {
281
+ latch.keys.clear();
282
+ latch.stick = null;
283
+ }
284
+ runtime.update(dt);
285
+ }
238
286
  // A behavior may have requested a scene switch; apply it here, between
239
287
  // frames, never mid physics dispatch. The load resets
240
288
  // registered systems -- the rapier world frees and lazily rebuilds --
241
289
  // while `runtime.persistent` carries the player's cross-scene state.
242
290
  if (runtime.requestedScene) {
243
- const next = loadRequestedScene(runtime);
291
+ const next = world.emptyNodesOwned
292
+ ? loadEmptyScene(world, runtime, loadRequestedScene)
293
+ : loadRequestedScene(runtime);
294
+ if (runtime.skipsEmptyNodes) prepareEmptyNodes(world, runtime);
244
295
  runtime.currentScenePath = next;
245
296
  runtime.persistent.sceneChangeGraceUntil = runtime.time + 1;
246
297
  }
247
298
  syncActors(world, runtime, runtime.sprites ?? sprites, dt);
248
299
  if (world.debugLines.visible) updatePhysicsDebug(world, runtime.physics3d?.debugRender());
249
- renderWorld(world, runtime);
300
+ // Under the orbit camera key the Player names its actor for this
301
+ // frame's draw, which leaves that model out when the camera is inside
302
+ // it (ownmodel.js). Without the key the field is never set and this
303
+ // is the call it always was.
304
+ if (runtime.orbitOwnModel !== undefined) renderHidingOwnModel(world, runtime, renderWorld);
305
+ else renderWorld(world, runtime);
250
306
  updateHud(runtime, hudRefs);
251
307
  } catch (err) {
252
308
  onError?.(err);
@@ -251,3 +251,89 @@ function write(object, record) {
251
251
  }
252
252
  record.sizes[index] = at - index;
253
253
  }
254
+
255
+ //
256
+ // Scenes that set `"engine": { "staticActors": true }`
257
+ //
258
+ // The node of an actor the scene's runtime holds still (world3d.js has the
259
+ // rule) stops asking, frame after frame, whether its subtree reads as it did:
260
+ // it is frozen. It gets there by its own check, never by being told: the world
261
+ // only says that a node may freeze (`freezeWhenUnchanged`), and the node
262
+ // freezes the next time the walk above finds it unchanged. From then on its
263
+ // `updateMatrixWorld` asks one thing and returns: is the node under the parent
264
+ // it was frozen under, and is that parent's world matrix, as three.js has
265
+ // just left it, the one the node's matrices were computed from? While that
266
+ // holds they stay as the walk left them, whether or not the node was out of
267
+ // the scene in between (hub-game takes far nodes out and puts them back under
268
+ // the same parent). The parent is asked on every walk, by whoever walks (a
269
+ // draw, or deck code calling `updateMatrixWorld`), because the scene can be
270
+ // moved by anything at any time and three.js computes a parent's world
271
+ // matrix before it walks the children: so the answer is about the very
272
+ // matrix this walk would multiply by, however it came to be (position,
273
+ // quaternion or scale set, the local or world matrix written by hand, the
274
+ // update flags, a parent of the scene's own). Nothing is predicted. When the
275
+ // parent or its matrix differs the node takes ActorNode's own check, which
276
+ // computes it again.
277
+ //
278
+ // What says a node is frozen is two numbers on it and one on the world's
279
+ // `skipping`: `freezes` and `frozenAt`, each the `skipping.epoch` it was
280
+ // written at. The world moves the epoch whenever anything a frozen node's
281
+ // matrices rest on may have changed, which thaws every node of the world at
282
+ // once, attached or not, with nothing to visit; a node thawed that way puts
283
+ // ActorNode's own method back the next time it is asked. And a frozen node is
284
+ // only frozen while no scene's still set has changed since the world adopted
285
+ // its own (`skipping.clock()`, the runtime's `stillClock`, against
286
+ // `skipping.clockAt`): `scene.touch` thaws at once, so an actor touched and
287
+ // then posed is followed by the very next walk, whoever makes it. Nothing here is
288
+ // reached unless a world calls `freezeWhenUnchanged`.
289
+
290
+ // `updateMatrixWorld` for a node that may freeze, set on the node itself over
291
+ // ActorNode's.
292
+ function updateMatrixWorldFreezing(force) {
293
+ const skipping = this.skipping;
294
+ if (skipping.on && this.frozenAt === skipping.epoch && skipping.clock() === skipping.clockAt && sameParent(this.parent, this.computedFrom)) {
295
+ return;
296
+ }
297
+ if (!skipping.on || this.freezes !== skipping.epoch) {
298
+ // The wish is of another epoch: an ActorNode again, and for good.
299
+ delete this.updateMatrixWorld;
300
+ delete this.freezes;
301
+ delete this.frozenAt;
302
+ this.updateMatrixWorld(force);
303
+ return;
304
+ }
305
+ const from = this.computedFrom;
306
+ if (from !== null && unchanged(this, from)) {
307
+ this.frozenAt = skipping.epoch;
308
+ return;
309
+ }
310
+ baseGroupUpdateMatrixWorld.call(this, force);
311
+ this.computedFrom = remember(this, from);
312
+ }
313
+
314
+ const baseGroupUpdateMatrixWorld = THREE.Group.prototype.updateMatrixWorld;
315
+
316
+ // Lets `node` freeze once its own check finds it unchanged, for as long as
317
+ // `node.skipping.epoch` stays what it is now.
318
+ export function freezeWhenUnchanged(node) {
319
+ if (node.freezes === node.skipping.epoch) return;
320
+ node.freezes = node.skipping.epoch;
321
+ node.frozenAt = undefined;
322
+ node.updateMatrixWorld = updateMatrixWorldFreezing;
323
+ }
324
+
325
+ // Whether `node` is frozen now (its parent aside, which it asks on each walk).
326
+ export function isFrozen(node) {
327
+ const skipping = node.skipping;
328
+ return skipping?.on === true && node.frozenAt !== undefined && node.frozenAt === skipping.epoch && skipping.clock() === skipping.clockAt;
329
+ }
330
+
331
+ // Whether the objects under `node`, and `node` itself, read as the last walk
332
+ // recorded them (its parent is not looked at: a node taken out of the scene is
333
+ // still itself). False for a node no walk has recorded. For an audit.
334
+ export function subtreeIsAsRecorded(node) {
335
+ const from = node.computedFrom;
336
+ if (!from) return false;
337
+ at = 0;
338
+ return sameSubtree(node, true, from) && at === from.ids.length;
339
+ }
@@ -0,0 +1,23 @@
1
+ // One cadence for the composed biped and authored-motion pose.
2
+ // A skipped frame must leave both passes untouched, and waking flushes time.
3
+ export function animationDt(entry, dt) {
4
+ const every = entry.node.userData.animationEvery;
5
+ const pending = entry.animationElapsed ?? 0;
6
+ if (!(Number.isFinite(every) && every > 0) || !(dt > 0)) {
7
+ if (entry.animationCadence !== undefined) {
8
+ delete entry.animationCadence;
9
+ delete entry.animationElapsed;
10
+ }
11
+ return dt > 0 ? dt + pending : dt;
12
+ }
13
+ if (entry.animationCadence !== every) {
14
+ entry.animationCadence = every;
15
+ entry.animationElapsed = 0;
16
+ return dt + pending;
17
+ }
18
+ entry.animationElapsed = pending + dt;
19
+ if (entry.animationElapsed + 1e-9 < every) return null;
20
+ const elapsed = entry.animationElapsed;
21
+ entry.animationElapsed = 0;
22
+ return elapsed;
23
+ }
@@ -8,12 +8,17 @@ import * as THREE from 'three';
8
8
  import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
9
9
  import { TransformControls } from 'three/examples/jsm/controls/TransformControls.js';
10
10
  import { makeWorld3D, resizeWorld, syncActors, renderWorld, disposeWorld } from './world3d';
11
+ import { forgetEmptyNodes } from './emptynodes';
11
12
  import { makeScene } from '@imports/castle.physics-2d/engine/scene';
12
13
 
13
14
  const CLICK_SLOP_PX = 5;
14
15
 
15
16
  export function createEditorWorld(canvas, callbacks) {
16
17
  const world = makeWorld3D(canvas);
18
+ // The editor changes actors as it pleases: nothing is held still here,
19
+ // whatever the scene's `engine.staticActors` says (world3d.js).
20
+ world.staticActorsOff = true;
21
+ world.skipEmptyNodesOff = true;
17
22
  world.camera.position.set(11, 10, 11);
18
23
 
19
24
  const orbit = new OrbitControls(world.camera, canvas);
@@ -239,6 +244,7 @@ function startEditorLoop(ed) {
239
244
  ed.resizeObserver.observe(ed.canvas);
240
245
  fit();
241
246
  const tick = () => {
247
+ if (ed.world.emptyNodes) forgetEmptyNodes(ed.world, true);
242
248
  ed.orbit.update();
243
249
  if (ed.runtime) syncActors(ed.world, ed.runtime, ed.sprites);
244
250
  syncGizmo(ed);
@@ -0,0 +1,232 @@
1
+ // Lifecycle owns the mode. Syncs and three.js listeners cannot enter it.
2
+ const bindings = new WeakMap();
3
+ const EVENTS = ['added', 'removed', 'childadded', 'childremoved'];
4
+
5
+ // Called only by the player after a keyed scene load has completed. A
6
+ // keyless player never calls this, binds a system, or allocates mode state.
7
+ export function prepareEmptyNodes(world, runtime) {
8
+ if (world.emptyNodesBlocked || world.emptyPass || world.emptyNodes?.dispatchDepth || world.disposed || world.skipEmptyNodesOff || !runtime.skipsEmptyNodes) return;
9
+ world.emptyNodesOwned = true;
10
+ world.emptyNodesBlocked = true;
11
+ try {
12
+ let bound = bindings.get(world);
13
+ if (bound?.runtime !== runtime) {
14
+ forgetEmptyNodes(world, true);
15
+ if (world.disposed) return;
16
+ bound = { runtime };
17
+ bindings.set(world, bound);
18
+ const reset = () => {
19
+ if (bindings.get(world) === bound) forgetEmptyNodes(world, true);
20
+ };
21
+ runtime.registerSystem({ reset, dispose: reset });
22
+ }
23
+ if (world.emptyNodes) return;
24
+ const state = { runtime, records: new Map(), dirty: new Set(), identity: sceneIsIdentity(world.scene), depth: 0, dispatchDepth: 0, draining: false };
25
+ world.emptyNodes = state;
26
+ state.sceneChanged = event => {
27
+ if (state.records.has(event.child)) state.dirty.add(event.child);
28
+ };
29
+ state.restoreDispatch = bracketDispatch(world.scene, state);
30
+ for (const event of ['childadded', 'childremoved']) world.scene.addEventListener(event, state.sceneChanged);
31
+ for (const entry of world.nodes.values()) watchEmptyNode(world, entry);
32
+ } finally {
33
+ delete world.emptyNodesBlocked;
34
+ }
35
+ }
36
+
37
+ // The player's load latch brackets the WHOLE load, including other systems'
38
+ // reset callbacks before our system is reached. Worlds that never asked do
39
+ // not call it.
40
+ export function loadEmptyScene(world, runtime, load) {
41
+ const blocked = world.emptyNodesBlocked;
42
+ world.emptyNodesBlocked = true;
43
+ try {
44
+ forgetEmptyNodes(world, true);
45
+ return load(runtime);
46
+ } finally {
47
+ if (blocked) world.emptyNodesBlocked = true;
48
+ else delete world.emptyNodesBlocked;
49
+ }
50
+ }
51
+
52
+ // Only keyed objects get a dispatch bracket. Preserve singleton event fields
53
+ // and cover ALL listeners, including a later listener that syncs or throws.
54
+ function bracketDispatch(node, state) {
55
+ const restorers = [];
56
+ // add/remove also bracket the child's added/removed dispatch, which three
57
+ // runs BEFORE the parent's child event. A throw there still queues dirty.
58
+ for (const method of ['dispatchEvent', 'add', 'remove']) {
59
+ const own = Object.getOwnPropertyDescriptor(node, method);
60
+ const original = node[method];
61
+ const bracket = function (...args) {
62
+ state.dispatchDepth++;
63
+ try { return original.apply(this, args); }
64
+ finally {
65
+ state.dispatchDepth--;
66
+ if (method !== 'dispatchEvent') {
67
+ if (state.records.has(node)) state.dirty.add(node);
68
+ else for (const child of args) if (state.records.has(child)) state.dirty.add(child);
69
+ }
70
+ }
71
+ };
72
+ node[method] = bracket;
73
+ restorers.push(() => {
74
+ if (node[method] !== bracket) return;
75
+ if (own) Object.defineProperty(node, method, own);
76
+ else delete node[method];
77
+ });
78
+ }
79
+ return () => { for (const restore of restorers) restore(); };
80
+ }
81
+
82
+ export const EMPTY_PASS_ABORTED = Symbol('empty actor pass invalidated');
83
+
84
+ // The active outer pass holds its original state even after reset deletes it.
85
+ export function checkEmptyPass(world, state = world.emptyPass) {
86
+ if (world.disposed || world.emptyNodes !== state) throw EMPTY_PASS_ABORTED;
87
+ }
88
+
89
+ // Detached matrices are world space only for an identity scene.
90
+ function sceneIsIdentity(scene) {
91
+ const p = scene.position;
92
+ const q = scene.quaternion;
93
+ const s = scene.scale;
94
+ if (scene.parent || p.x || p.y || p.z || q.x || q.y || q.z || q.w !== 1 || s.x !== 1 || s.y !== 1 || s.z !== 1) return false;
95
+ if (!scene.matrixAutoUpdate) {
96
+ const e = scene.matrix.elements;
97
+ for (let i = 0; i < 16; i++) if (e[i] !== (i % 5 === 0 ? 1 : 0)) return false;
98
+ }
99
+ return scene.matrixWorldAutoUpdate === true;
100
+ }
101
+
102
+ export function watchEmptyNode(world, entry) {
103
+ const state = world.emptyNodes;
104
+ const node = entry.node;
105
+ if (state.records.has(node)) return;
106
+ const record = { entry, restoreDispatch: bracketDispatch(node, state), changed: () => {
107
+ state.dirty.add(node);
108
+ } };
109
+ state.records.set(node, record);
110
+ for (const event of EVENTS) node.addEventListener(event, record.changed);
111
+ state.dirty.add(node);
112
+ }
113
+
114
+ function unwatch(node, record) {
115
+ for (const event of EVENTS) node.removeEventListener(event, record.changed);
116
+ record.restoreDispatch();
117
+ delete node.emptyDetached;
118
+ }
119
+
120
+ export function releaseEmptyNode(world, node) {
121
+ const state = world.emptyNodes;
122
+ const record = state.records.get(node);
123
+ if (!record) return;
124
+ unwatch(node, record);
125
+ state.records.delete(node);
126
+ state.dirty.delete(node);
127
+ }
128
+
129
+ // Adoption is a one-time engine point; settled static roots are never visited.
130
+ export function freezeEmptyNode(world, node) {
131
+ if (node.emptyDetached) updateEmptyNode(node);
132
+ }
133
+
134
+ export function updateEmptyNode(node) {
135
+ node.updateMatrixWorld();
136
+ if (node.freezes !== undefined && node.freezes === node.skipping.epoch && node.frozenAt !== node.skipping.epoch) node.updateMatrixWorld();
137
+ }
138
+
139
+ function reconcile(world, state, node, record) {
140
+ if (world.nodes.get(node.userData.actorId) !== record.entry) return;
141
+ if (node.children.length === 0 && state.identity) {
142
+ if (node.parent === world.scene) {
143
+ node.emptyDetached = true;
144
+ world.scene.remove(node);
145
+ checkEmptyPass(world, state);
146
+ // Removal listeners can move the scene. A detached local matrix is
147
+ // no longer world space then, so restore this node before proceeding.
148
+ if (!sceneIsIdentity(world.scene)) {
149
+ delete node.emptyDetached;
150
+ if (!node.parent) world.scene.add(node);
151
+ checkEmptyPass(world, state);
152
+ } else if (!node.parent && !node.children.length) updateEmptyNode(node);
153
+ }
154
+ } else if (node.emptyDetached) {
155
+ delete node.emptyDetached;
156
+ // A consumer's deliberate hiding/reparenting remains its own.
157
+ if (!node.parent) world.scene.add(node);
158
+ checkEmptyPass(world, state);
159
+ }
160
+ }
161
+
162
+ // Only at the START of an outermost sync, never on its way out. Events fired
163
+ // in the body wait for the next sync. A dispatch bracket defers reentrant
164
+ // syncs without trusting event.target, which a throwing listener can strand.
165
+ export function syncEmptyNodes(world, state) {
166
+ if (state.draining || state.dispatchDepth) return;
167
+ checkEmptyPass(world, state);
168
+ const identity = sceneIsIdentity(world.scene);
169
+ if (identity !== state.identity) {
170
+ state.identity = identity;
171
+ for (const node of state.records.keys()) state.dirty.add(node);
172
+ }
173
+ if (state.dirty.size === 0) return;
174
+ const pending = [...state.dirty];
175
+ state.dirty.clear();
176
+ state.draining = true;
177
+ let index = 0;
178
+ try {
179
+ for (; index < pending.length; index++) {
180
+ const node = pending[index];
181
+ const record = state.records.get(node);
182
+ if (record) reconcile(world, state, node, record);
183
+ checkEmptyPass(world, state);
184
+ // Both removal and attachment run foreign listeners. Recheck before
185
+ // the next detach, and revisit earlier detached roots in this pass.
186
+ const identity = sceneIsIdentity(world.scene);
187
+ if (identity !== state.identity) {
188
+ state.identity = identity;
189
+ for (const node of state.records.keys()) pending.push(node);
190
+ }
191
+ }
192
+ } catch (error) {
193
+ if (!world.disposed && world.emptyNodes === state) {
194
+ for (; index < pending.length; index++) state.dirty.add(pending[index]);
195
+ }
196
+ throw error;
197
+ } finally {
198
+ state.draining = false;
199
+ }
200
+ }
201
+
202
+ export function forgetEmptyNodes(world, restore = false) {
203
+ const state = world.emptyNodes;
204
+ if (!state) return;
205
+ // Guard the entire restore, including reentrant loads from consumer code.
206
+ const blocked = world.emptyNodesBlocked;
207
+ world.emptyNodesBlocked = true;
208
+ delete world.emptyNodes;
209
+ state.draining = true;
210
+ const restoreNodes = [];
211
+ for (const [node, record] of state.records) {
212
+ if (restore && node.emptyDetached) restoreNodes.push([node, record.entry]);
213
+ unwatch(node, record);
214
+ }
215
+ for (const event of ['childadded', 'childremoved']) world.scene.removeEventListener(event, state.sceneChanged);
216
+ state.restoreDispatch();
217
+ let failed = null;
218
+ try {
219
+ for (const [node, entry] of restoreNodes) {
220
+ if (world.disposed) break;
221
+ if (!node.parent && world.nodes.get(node.userData.actorId) === entry) {
222
+ try { world.scene.add(node); } catch (error) { failed ??= { error }; }
223
+ }
224
+ }
225
+ } finally {
226
+ state.records.clear();
227
+ state.dirty.clear();
228
+ if (blocked) world.emptyNodesBlocked = true;
229
+ else delete world.emptyNodesBlocked;
230
+ }
231
+ if (failed) throw failed.error;
232
+ }