castle-web-cli 0.4.231 → 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 (368) 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/serverBundle.js +5 -3
  28. package/dist/shell/assets/{index-D2tWM896.js → index-BjOxR-lW.js} +4 -4
  29. package/dist/shell/assets/index-MVLfNYd9.css +1 -0
  30. package/dist/shell/index.html +2 -2
  31. package/dist/taskSteer.d.ts +13 -0
  32. package/dist/taskSteer.js +22 -2
  33. package/kits/base/castle.json +1 -1
  34. package/kits/base/package-lock.json +1 -1
  35. package/kits/base/sdk/README.md +79 -2
  36. package/kits/base/sdk/avatar.d.ts +6 -2
  37. package/kits/base/sdk/avatar.js +12 -4
  38. package/kits/base/sdk/castle.d.ts +1 -1
  39. package/kits/base/sdk/commands.d.ts +14 -0
  40. package/kits/base/sdk/hub.d.ts +6 -2
  41. package/kits/base/sdk/hub.js +13 -0
  42. package/kits/base/sdk/multiplayer.js +17 -1
  43. package/kits/base/sdk/save.js +2 -1
  44. package/kits/base/sdk/server/hub.d.ts +87 -0
  45. package/kits/base/sdk/server/hub.js +70 -0
  46. package/kits/base/sdk/server/platformHandle.d.ts +31 -1
  47. package/kits/base/sdk/server/storage.d.ts +13 -0
  48. package/kits/base/sdk/server/storage.js +46 -0
  49. package/kits/base/sdk/server/wrapper.d.ts +36 -5
  50. package/kits/base/sdk/server/wrapper.js +83 -8
  51. package/kits/hub-game/CLAUDE.md +352 -12
  52. package/kits/hub-game/blueprints/avatar-10.scene +28 -0
  53. package/kits/hub-game/blueprints/avatar-11.scene +28 -0
  54. package/kits/hub-game/blueprints/avatar-12.scene +28 -0
  55. package/kits/hub-game/blueprints/avatar-13.scene +28 -0
  56. package/kits/hub-game/blueprints/avatar-14.scene +28 -0
  57. package/kits/hub-game/blueprints/avatar-15.scene +28 -0
  58. package/kits/hub-game/blueprints/avatar-4.scene +28 -0
  59. package/kits/hub-game/blueprints/avatar-5.scene +28 -0
  60. package/kits/hub-game/blueprints/avatar-6.scene +28 -0
  61. package/kits/hub-game/blueprints/avatar-7.scene +28 -0
  62. package/kits/hub-game/blueprints/avatar-8.scene +28 -0
  63. package/kits/hub-game/blueprints/avatar-9.scene +28 -0
  64. package/kits/hub-game/code/client/actorBudget.js +47 -0
  65. package/kits/hub-game/code/client/attention.js +11 -2
  66. package/kits/hub-game/code/client/avatar.js +345 -32
  67. package/kits/hub-game/code/client/avatarCap.js +228 -0
  68. package/kits/hub-game/code/client/avatarColors.js +70 -0
  69. package/kits/hub-game/code/client/avatarFaces.js +21 -0
  70. package/kits/hub-game/code/client/avatarShare.js +251 -0
  71. package/kits/hub-game/code/client/ballot.js +467 -0
  72. package/kits/hub-game/code/client/build.js +22 -0
  73. package/kits/hub-game/code/client/chat.js +12 -0
  74. package/kits/hub-game/code/client/chrome.js +1334 -50
  75. package/kits/hub-game/code/client/companion.js +716 -0
  76. package/kits/hub-game/code/client/companionDress.js +99 -0
  77. package/kits/hub-game/code/client/decor.js +509 -0
  78. package/kits/hub-game/code/client/earned.js +131 -0
  79. package/kits/hub-game/code/client/emoteBubble.js +75 -0
  80. package/kits/hub-game/code/client/grab.js +363 -20
  81. package/kits/hub-game/code/client/hats.js +26 -0
  82. package/kits/hub-game/code/client/hookLayer.js +328 -15
  83. package/kits/hub-game/code/client/hudClear.js +126 -0
  84. package/kits/hub-game/code/client/idle.js +163 -22
  85. package/kits/hub-game/code/client/interestCap.js +81 -0
  86. package/kits/hub-game/code/client/keys.js +36 -0
  87. package/kits/hub-game/code/client/labelsNear.js +205 -0
  88. package/kits/hub-game/code/client/menuIcons.js +34 -0
  89. package/kits/hub-game/code/client/pack.js +6 -2
  90. package/kits/hub-game/code/client/packFormat.js +3 -3
  91. package/kits/hub-game/code/client/rehello.js +167 -0
  92. package/kits/hub-game/code/client/shot.js +92 -0
  93. package/kits/hub-game/code/client/sound.js +63 -8
  94. package/kits/hub-game/code/client/soundscape.js +1151 -0
  95. package/kits/hub-game/code/client/soundscapeActions.js +99 -0
  96. package/kits/hub-game/code/client/soundscapeAmbience.js +453 -0
  97. package/kits/hub-game/code/client/soundscapeBaked.js +143 -0
  98. package/kits/hub-game/code/client/soundscapeBusker.js +217 -0
  99. package/kits/hub-game/code/client/soundscapeCourt.js +200 -0
  100. package/kits/hub-game/code/client/soundscapeCrowd.js +331 -0
  101. package/kits/hub-game/code/client/soundscapeCues.js +362 -0
  102. package/kits/hub-game/code/client/soundscapeMap.js +181 -0
  103. package/kits/hub-game/code/client/soundscapeMarket.js +176 -0
  104. package/kits/hub-game/code/client/soundscapeMusic.js +126 -0
  105. package/kits/hub-game/code/client/soundscapeMusicEngine.js +460 -0
  106. package/kits/hub-game/code/client/soundscapeSimlish.js +737 -0
  107. package/kits/hub-game/code/client/soundscapeSongs.js +127 -0
  108. package/kits/hub-game/code/client/soundscapeSongsRound3.js +63 -0
  109. package/kits/hub-game/code/client/soundscapeSynthesis.js +168 -0
  110. package/kits/hub-game/code/client/soundscapeUi.js +211 -0
  111. package/kits/hub-game/code/client/soundscapeVoice.js +1209 -0
  112. package/kits/hub-game/code/client/soundscapeWaves.js +206 -0
  113. package/kits/hub-game/code/client/spin.js +101 -0
  114. package/kits/hub-game/code/client/state.js +131 -1
  115. package/kits/hub-game/code/client/stuck.js +259 -0
  116. package/kits/hub-game/code/client/talk.js +538 -47
  117. package/kits/hub-game/code/client/tiers.js +541 -27
  118. package/kits/hub-game/code/client/toastBand.js +37 -0
  119. package/kits/hub-game/code/client/together.js +98 -1
  120. package/kits/hub-game/code/client/visibility.js +43 -0
  121. package/kits/hub-game/code/client/wear.js +470 -97
  122. package/kits/hub-game/code/client/yours.js +199 -0
  123. package/kits/hub-game/code/companionSpec.js +45 -0
  124. package/kits/hub-game/code/privateText.js +7 -0
  125. package/kits/hub-game/code/server/actions.js +133 -0
  126. package/kits/hub-game/code/server/actors.js +14 -1
  127. package/kits/hub-game/code/server/ask.js +155 -0
  128. package/kits/hub-game/code/server/ballot.js +539 -0
  129. package/kits/hub-game/code/server/cells.js +100 -0
  130. package/kits/hub-game/code/server/companion.js +82 -0
  131. package/kits/hub-game/code/server/cues.js +70 -0
  132. package/kits/hub-game/code/server/decor.js +269 -0
  133. package/kits/hub-game/code/server/earned.js +461 -0
  134. package/kits/hub-game/code/server/friendBests.js +166 -0
  135. package/kits/hub-game/code/server/friendsAmong.js +232 -0
  136. package/kits/hub-game/code/server/grab.js +296 -11
  137. package/kits/hub-game/code/server/history.js +5 -0
  138. package/kits/hub-game/code/server/hub.js +1317 -52
  139. package/kits/hub-game/code/server/idle.js +30 -11
  140. package/kits/hub-game/code/server/index.js +2 -2
  141. package/kits/hub-game/code/server/labels.js +28 -2
  142. package/kits/hub-game/code/server/manifest.js +424 -8
  143. package/kits/hub-game/code/server/menu.js +133 -0
  144. package/kits/hub-game/code/server/npcs.js +830 -80
  145. package/kits/hub-game/code/server/party.js +13 -2
  146. package/kits/hub-game/code/server/players.js +22 -0
  147. package/kits/hub-game/code/server/say.js +8 -2
  148. package/kits/hub-game/code/server/shot.js +110 -0
  149. package/kits/hub-game/code/server/standing.js +124 -0
  150. package/kits/hub-game/code/server/vis.js +113 -0
  151. package/kits/hub-game/code/server/wear.js +128 -11
  152. package/kits/hub-game/code/server/yours.js +59 -0
  153. package/kits/hub-game/code/shared/cues.js +9 -0
  154. package/kits/hub-game/code/shared/decor.js +41 -0
  155. package/kits/hub-game/code/shared/shot.js +19 -0
  156. package/kits/hub-game/code/shared/spin.js +57 -0
  157. package/kits/hub-game/code/systems/hub.js +1083 -85
  158. package/kits/hub-game/docs/content-pack.md +1 -1
  159. package/kits/hub-game/docs/contract.md +2440 -61
  160. package/kits/hub-game/docs/home-pieces.md +64 -0
  161. package/kits/hub-game/models/avatar-10.pxmodel +28 -0
  162. package/kits/hub-game/models/avatar-11.pxmodel +28 -0
  163. package/kits/hub-game/models/avatar-12.pxmodel +27 -0
  164. package/kits/hub-game/models/avatar-13.pxmodel +24 -0
  165. package/kits/hub-game/models/avatar-14.pxmodel +29 -0
  166. package/kits/hub-game/models/avatar-15.pxmodel +24 -0
  167. package/kits/hub-game/models/avatar-4.pxmodel +29 -0
  168. package/kits/hub-game/models/avatar-5.pxmodel +27 -0
  169. package/kits/hub-game/models/avatar-6.pxmodel +26 -0
  170. package/kits/hub-game/models/avatar-7.pxmodel +25 -0
  171. package/kits/hub-game/models/avatar-8.pxmodel +24 -0
  172. package/kits/hub-game/models/avatar-9.pxmodel +30 -0
  173. package/kits/hub-game/models/earned/badge-round.pxmodel +100 -0
  174. package/kits/hub-game/models/earned/badge-shield.pxmodel +117 -0
  175. package/kits/hub-game/models/earned/badge-star.pxmodel +87 -0
  176. package/kits/hub-game/models/earned/belt-plain.pxmodel +72 -0
  177. package/kits/hub-game/models/earned/held-ball.pxmodel +43 -0
  178. package/kits/hub-game/models/earned/held-lantern.pxmodel +85 -0
  179. package/kits/hub-game/models/earned/held-net.pxmodel +57 -0
  180. package/kits/hub-game/models/earned/held-trophy.pxmodel +109 -0
  181. package/kits/hub-game/models/earned/pin-round.pxmodel +62 -0
  182. package/kits/hub-game/models/earned/sash-plain.pxmodel +66 -0
  183. package/kits/hub-game/models/earned/square/belt-plain.pxmodel +104 -0
  184. package/kits/hub-game/models/earned/square/sash-plain.pxmodel +98 -0
  185. package/kits/hub-game/models/hats/bat-clip.pxmodel +206 -0
  186. package/kits/hub-game/models/hats/beekeeper.pxmodel +149 -0
  187. package/kits/hub-game/models/hats/cap.pxmodel +162 -0
  188. package/kits/hub-game/models/hats/captain.pxmodel +178 -0
  189. package/kits/hub-game/models/hats/crooked-top.pxmodel +172 -0
  190. package/kits/hub-game/models/hats/flower-crown.pxmodel +451 -0
  191. package/kits/hub-game/models/hats/foam-crown.pxmodel +179 -0
  192. package/kits/hub-game/models/hats/lantern.pxmodel +230 -0
  193. package/kits/hub-game/models/hats/laurel.pxmodel +533 -0
  194. package/kits/hub-game/models/hats/lighthouse.pxmodel +96 -0
  195. package/kits/hub-game/models/hats/sailor.pxmodel +141 -0
  196. package/kits/hub-game/models/hats/souwester.pxmodel +131 -0
  197. package/kits/hub-game/models/hats/straw.pxmodel +139 -0
  198. package/kits/hub-game/models/hats/sunflower.pxmodel +406 -0
  199. package/kits/hub-game/models/hats/sweatband.pxmodel +112 -0
  200. package/kits/hub-game/models/hats/witch.pxmodel +147 -0
  201. package/kits/hub-game/package-lock.json +2 -0
  202. package/kits/hub-game/package.json +2 -1
  203. package/kits/hub-game/scripts/check.mjs +78 -11
  204. package/kits/hub-game/scripts/companion-follower-wire.json +1 -0
  205. package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +121 -0
  206. package/kits/hub-game/scripts/fixtures/decor-keyless.json +293 -0
  207. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +23 -0
  208. package/kits/hub-game/scripts/fixtures/fake-dom.mjs +107 -0
  209. package/kits/hub-game/scripts/fixtures/interest-legacy.json +385 -0
  210. package/kits/hub-game/scripts/fixtures/npc-notes-v1.77.jsonl +4 -0
  211. package/kits/hub-game/scripts/fixtures/vis-shared-wire.json +1 -0
  212. package/kits/hub-game/scripts/gen-avatars.mjs +933 -16
  213. package/kits/hub-game/scripts/gen-earned.mjs +285 -0
  214. package/kits/hub-game/scripts/gen-hats.mjs +827 -0
  215. package/kits/hub-game/scripts/grab.before-orbit.mjs +400 -0
  216. package/kits/hub-game/scripts/soundscape-wave-analysis.mjs +125 -0
  217. package/kits/hub-game/scripts/test-actions-client.mjs +488 -0
  218. package/kits/hub-game/scripts/test-actions.mjs +298 -0
  219. package/kits/hub-game/scripts/test-actor-budget.mjs +44 -0
  220. package/kits/hub-game/scripts/test-actors.mjs +19 -17
  221. package/kits/hub-game/scripts/test-ask-client.mjs +358 -0
  222. package/kits/hub-game/scripts/test-ask.mjs +269 -0
  223. package/kits/hub-game/scripts/test-attention.mjs +10 -1
  224. package/kits/hub-game/scripts/test-avatar-cap.mjs +379 -0
  225. package/kits/hub-game/scripts/test-avatar-colors.mjs +72 -0
  226. package/kits/hub-game/scripts/test-avatar-models.mjs +181 -0
  227. package/kits/hub-game/scripts/test-avatar-share.mjs +318 -0
  228. package/kits/hub-game/scripts/test-avatar-wire.mjs +753 -0
  229. package/kits/hub-game/scripts/test-avatar.mjs +540 -7
  230. package/kits/hub-game/scripts/test-ballot.mjs +1001 -0
  231. package/kits/hub-game/scripts/test-build.mjs +31 -0
  232. package/kits/hub-game/scripts/test-cells.mjs +71 -0
  233. package/kits/hub-game/scripts/test-chat.mjs +694 -0
  234. package/kits/hub-game/scripts/test-classic.mjs +2 -0
  235. package/kits/hub-game/scripts/test-companion-chat.mjs +198 -0
  236. package/kits/hub-game/scripts/test-companion-client.mjs +1167 -0
  237. package/kits/hub-game/scripts/test-companion.mjs +259 -0
  238. package/kits/hub-game/scripts/test-decor-client.mjs +303 -0
  239. package/kits/hub-game/scripts/test-decor.mjs +457 -0
  240. package/kits/hub-game/scripts/test-earned-client.mjs +459 -0
  241. package/kits/hub-game/scripts/test-earned.mjs +1194 -0
  242. package/kits/hub-game/scripts/test-emote-bubble.mjs +110 -0
  243. package/kits/hub-game/scripts/test-friend-bests.mjs +435 -0
  244. package/kits/hub-game/scripts/test-grab-client.mjs +186 -3
  245. package/kits/hub-game/scripts/test-grab-orbit.mjs +918 -0
  246. package/kits/hub-game/scripts/test-grab.mjs +864 -3
  247. package/kits/hub-game/scripts/test-hats.mjs +483 -0
  248. package/kits/hub-game/scripts/test-hub-leaving.mjs +203 -0
  249. package/kits/hub-game/scripts/test-hub-ops.mjs +439 -2
  250. package/kits/hub-game/scripts/test-hub-trip.mjs +1228 -1
  251. package/kits/hub-game/scripts/test-hud-clear.mjs +1000 -0
  252. package/kits/hub-game/scripts/test-idle.mjs +361 -1
  253. package/kits/hub-game/scripts/test-interest-cap.mjs +36 -0
  254. package/kits/hub-game/scripts/test-interest-cells.mjs +493 -0
  255. package/kits/hub-game/scripts/test-interest-client.mjs +118 -0
  256. package/kits/hub-game/scripts/test-keys.mjs +46 -1
  257. package/kits/hub-game/scripts/test-labels.mjs +596 -0
  258. package/kits/hub-game/scripts/test-manifest.mjs +282 -0
  259. package/kits/hub-game/scripts/test-menu-client.mjs +480 -0
  260. package/kits/hub-game/scripts/test-menu.mjs +296 -0
  261. package/kits/hub-game/scripts/test-npcs.mjs +1718 -12
  262. package/kits/hub-game/scripts/test-object-entry.mjs +76 -0
  263. package/kits/hub-game/scripts/test-pack.mjs +7 -0
  264. package/kits/hub-game/scripts/test-party.mjs +22 -1
  265. package/kits/hub-game/scripts/test-picker.mjs +314 -0
  266. package/kits/hub-game/scripts/test-rehello.mjs +1039 -0
  267. package/kits/hub-game/scripts/test-relations-among.mjs +222 -0
  268. package/kits/hub-game/scripts/test-relations-refresh.mjs +188 -0
  269. package/kits/hub-game/scripts/test-say.mjs +59 -2
  270. package/kits/hub-game/scripts/test-shot.mjs +756 -0
  271. package/kits/hub-game/scripts/test-soundscape.mjs +5432 -0
  272. package/kits/hub-game/scripts/test-spin.mjs +314 -0
  273. package/kits/hub-game/scripts/test-standing.mjs +416 -0
  274. package/kits/hub-game/scripts/test-stuck.mjs +1903 -0
  275. package/kits/hub-game/scripts/test-tier-cells.mjs +706 -0
  276. package/kits/hub-game/scripts/test-tiers-render.mjs +339 -0
  277. package/kits/hub-game/scripts/test-tiers.mjs +666 -3
  278. package/kits/hub-game/scripts/test-toast-band.mjs +61 -0
  279. package/kits/hub-game/scripts/test-try-on.mjs +940 -0
  280. package/kits/hub-game/scripts/test-vis.mjs +343 -0
  281. package/kits/hub-game/scripts/test-visibility.mjs +134 -0
  282. package/kits/hub-game/scripts/test-yours-chrome.mjs +166 -0
  283. package/kits/hub-game/scripts/test-yours.mjs +372 -0
  284. package/kits/multiplayer-3d/CLAUDE.md +50 -0
  285. package/kits/multiplayer-3d/castle.json +5 -5
  286. package/kits/multiplayer-3d/code/client/avatars.js +7 -0
  287. package/kits/multiplayer-3d/code/client/gait.js +65 -0
  288. package/kits/multiplayer-3d/code/client/nameTags.js +59 -4
  289. package/kits/multiplayer-3d/code/options.js +5 -0
  290. package/kits/multiplayer-3d/code/server/ownership.js +10 -2
  291. package/kits/multiplayer-3d/code/server/sceneBodies.js +12 -0
  292. package/kits/multiplayer-3d/code/server/world.js +7 -0
  293. package/kits/multiplayer-3d/code/systems/multiplayer.js +74 -4
  294. package/kits/multiplayer-3d/package.json +2 -1
  295. package/kits/multiplayer-3d/scripts/fixtures/README.md +11 -0
  296. package/kits/multiplayer-3d/scripts/fixtures/ownership-legacy.json +2 -0
  297. package/kits/multiplayer-3d/scripts/ownership-harness.mjs +102 -0
  298. package/kits/multiplayer-3d/scripts/ownership-loader.mjs +46 -0
  299. package/kits/multiplayer-3d/scripts/ownership-worker.mjs +15 -0
  300. package/kits/multiplayer-3d/scripts/record-ownership-session.mjs +98 -0
  301. package/kits/multiplayer-3d/scripts/test-eligible-claims.mjs +167 -0
  302. package/kits/multiplayer-3d/scripts/test-own-name-tag.mjs +247 -0
  303. package/kits/physics-2d/CLAUDE.md +9 -0
  304. package/kits/physics-2d/castle.json +2 -2
  305. package/kits/physics-2d/engine/scene.js +288 -1
  306. package/kits/physics-2d/engine/skyKey.js +129 -0
  307. package/kits/physics-2d/engine/stillClock.js +106 -0
  308. package/kits/physics-2d/engine/updateBudget.js +21 -0
  309. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +370 -1
  310. package/kits/physics-3d/CLAUDE.md +1391 -0
  311. package/kits/physics-3d/behaviors/Player.jsx +921 -3
  312. package/kits/physics-3d/castle.json +3 -3
  313. package/kits/physics-3d/docs/pxmodel-format.md +12 -0
  314. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +98 -10
  315. package/kits/physics-3d/engine3d/actornode.js +86 -0
  316. package/kits/physics-3d/engine3d/animationBudget.js +23 -0
  317. package/kits/physics-3d/engine3d/editorWorld.js +6 -0
  318. package/kits/physics-3d/engine3d/emptynodes.js +232 -0
  319. package/kits/physics-3d/engine3d/framecap.js +96 -0
  320. package/kits/physics-3d/engine3d/gait.js +118 -0
  321. package/kits/physics-3d/engine3d/kithooks.js +47 -0
  322. package/kits/physics-3d/engine3d/look.js +507 -48
  323. package/kits/physics-3d/engine3d/lookbake.js +208 -0
  324. package/kits/physics-3d/engine3d/materialpresets.js +2 -0
  325. package/kits/physics-3d/engine3d/motion.js +39 -10
  326. package/kits/physics-3d/engine3d/nearshadows.js +37 -19
  327. package/kits/physics-3d/engine3d/optimize.js +58 -5
  328. package/kits/physics-3d/engine3d/orbitinput.js +755 -0
  329. package/kits/physics-3d/engine3d/orbitlens.js +48 -0
  330. package/kits/physics-3d/engine3d/ownmodel.js +213 -0
  331. package/kits/physics-3d/engine3d/pxmodel.js +42 -11
  332. package/kits/physics-3d/engine3d/shadowfade.js +882 -0
  333. package/kits/physics-3d/engine3d/sky.js +547 -0
  334. package/kits/physics-3d/engine3d/skylife.js +306 -0
  335. package/kits/physics-3d/engine3d/unchanged.js +11 -0
  336. package/kits/physics-3d/engine3d/viewrange.js +52 -0
  337. package/kits/physics-3d/engine3d/world3d.js +870 -87
  338. package/kits/physics-3d/main.jsx +5 -0
  339. package/kits/physics-3d/package.json +1 -1
  340. package/kits/physics-3d/scripts/Player.before-orbit.mjs +310 -0
  341. package/kits/physics-3d/scripts/Scene3DPlayer.before-orbit.jsx +337 -0
  342. package/kits/physics-3d/scripts/look-baseline.mjs +155 -0
  343. package/kits/physics-3d/scripts/test-camera-follow.mjs +12 -2
  344. package/kits/physics-3d/scripts/test-camera-orbit.mjs +4588 -0
  345. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +787 -0
  346. package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +435 -0
  347. package/kits/physics-3d/scripts/test-frame-cap.mjs +452 -0
  348. package/kits/physics-3d/scripts/test-gait.mjs +387 -0
  349. package/kits/physics-3d/scripts/test-look-bake.mjs +1056 -0
  350. package/kits/physics-3d/scripts/test-model-parse-cache.mjs +92 -0
  351. package/kits/physics-3d/scripts/test-near-shadows.mjs +3 -0
  352. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +1920 -0
  353. package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +545 -0
  354. package/kits/physics-3d/scripts/test-orbit-shot.mjs +583 -0
  355. package/kits/physics-3d/scripts/test-orbit-view.mjs +230 -0
  356. package/kits/physics-3d/scripts/test-skip-empty-nodes.mjs +845 -0
  357. package/kits/physics-3d/scripts/test-sky.mjs +2470 -0
  358. package/kits/physics-3d/scripts/test-static-actors.mjs +13 -1
  359. package/kits/physics-3d/scripts/test-static-passes.mjs +1 -1
  360. package/kits/physics-3d/scripts/test-static-scenery.mjs +2171 -0
  361. package/kits/physics-3d/scripts/test-steady-hover.mjs +635 -0
  362. package/kits/physics-3d/scripts/test-view-range.mjs +260 -0
  363. package/kits/physics-3d/systems/physics3d.js +474 -12
  364. package/kits/real-time/castle.json +2 -2
  365. package/kits/real-time/code/server/gameHooks.js +7 -0
  366. package/kits/real-time/code/server/session.js +97 -19
  367. package/package.json +2 -2
  368. 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-04T22:43:17.146Z"
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-04T22:44:03.895Z"
64
+ "publishedVersion": "2026-10-08T15:11:19.728Z"
65
65
  }
@@ -672,6 +672,10 @@ time.
672
672
  - `keep: true` on a part keeps it out of merging, with its own mesh and
673
673
  material, for a deck that reaches for it by id. Parts with a `tint` are
674
674
  kept too.
675
+ - In a scene that set `"engine": { "dropEmptyParts": true }` (CLAUDE.md) a
676
+ placed model has no group for a part that draws nothing. `keep: true` is
677
+ also what keeps such a part's group there, for a deck that reaches for an
678
+ empty part as a locator; `slot-...` parts and parts that move always stay.
675
679
  - The same static model placed many times is built once, and in play every
676
680
  copy draws in the same calls.
677
681
  - What costs the most: fine paint over large areas (grime with a `scale`
@@ -866,6 +870,14 @@ drawn apart from the rest (see Cost), so move the few parts that matter.
866
870
 
867
871
  ### Gaits
868
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
+
869
881
  These part ids animate from the actor's observed motion (anything that
870
882
  moves, walks):
871
883
 
@@ -12,6 +12,10 @@ import {
12
12
  disposeWorld,
13
13
  updatePhysicsDebug,
14
14
  } from './world3d';
15
+ import { prepareEmptyNodes, loadEmptyScene } from './emptynodes';
16
+ import { attachOrbitInput } from './orbitinput';
17
+ import { renderHidingOwnModel } from './ownmodel';
18
+ import { makeFrameClock, makeInputLatch, nextFrame, updateLending } from './framecap';
15
19
 
16
20
  export function Scene3DPlayer({
17
21
  sceneData,
@@ -33,6 +37,9 @@ export function Scene3DPlayer({
33
37
  const runtime = makeScene(sceneData, behaviorClasses, sprites, files, scenePath);
34
38
  const world = makeWorld3D(canvas);
35
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();
36
43
  runtime.hud = {};
37
44
  // Scene-independent state: survives `loadFromFile` (the scene data is
38
45
  // replaced, the runtime instance is not). Player score/inventory and the
@@ -43,14 +50,16 @@ export function Scene3DPlayer({
43
50
  // deck's content, mounted as data); a caller checks before asking.
44
51
  runtime.mountsContent = true;
45
52
 
46
- 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);
47
56
  const stopResize = attachResize(canvas, world);
48
57
  const onLoopError = (err) => {
49
58
  console.error(err);
50
59
  setError(err);
51
60
  };
52
61
  const hudRefs = { score: scoreRef, look: lookRef };
53
- const stopLoop = startLoop(runtime, world, sprites, hudRefs, onFirstFrame, onLoopError);
62
+ const stopLoop = startLoop(runtime, world, sprites, hudRefs, onFirstFrame, onLoopError, latch);
54
63
  return () => {
55
64
  stopLoop();
56
65
  stopResize();
@@ -89,15 +98,25 @@ export function Scene3DPlayer({
89
98
  );
90
99
  }
91
100
 
92
- function attachInput(canvas, runtime, world) {
101
+ function attachInput(canvas, runtime, world, latch) {
93
102
  const onKeyDown = (event) => {
94
103
  // Space is gameplay (jump); keep it from scrolling the page.
95
104
  if (event.code === 'Space' && event.target === canvas) event.preventDefault();
96
105
  if (event.code === 'KeyP' && !event.repeat) {
97
106
  world.debugLines.visible = !world.debugLines.visible;
98
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
+ }
99
112
  runtime.keys.add(event.code);
100
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
+ }
101
120
  };
102
121
  const onKeyUp = (event) => {
103
122
  runtime.keys.delete(event.code);
@@ -134,7 +153,38 @@ function attachInput(canvas, runtime, world) {
134
153
  move.x = 0;
135
154
  move.y = 0;
136
155
  };
156
+ // A scene that set `"engine": { "camera": { "control": "orbit" } }` beside
157
+ // `"follow": "rigid"`: a pointer that goes down in it is orbitinput.js's
158
+ // from then until it lifts (or a scene loads). It is made the first time
159
+ // a pointer goes down under the key, Shift is pressed there, or a Player runs under it
160
+ // (`runtime.orbitInput()`), never in a runtime that does not meet the key.
161
+ // Without the key each handler below reads one property and goes on as it
162
+ // always did.
163
+ let orbit = null;
164
+ runtime.orbitInput = () =>
165
+ (orbit ??= attachOrbitInput(
166
+ canvas,
167
+ runtime,
168
+ move,
169
+ () => {
170
+ jumpPending = true;
171
+ },
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)
176
+ ));
137
177
  const onPointerDown = (event) => {
178
+ if (runtime.cameraControl === 'orbit') {
179
+ // Fingers that went down before the key (a scene without it was
180
+ // loaded then) are let go of here, so they and orbitinput.js never
181
+ // both write the stick: the handlers below ignore them from now on.
182
+ if (pointers.size > 0 || stickId !== null) {
183
+ pointers.clear();
184
+ clearStick();
185
+ }
186
+ return runtime.orbitInput().down(event);
187
+ }
138
188
  canvas.focus();
139
189
  pointers.set(event.pointerId, {
140
190
  x: event.clientX,
@@ -142,9 +192,19 @@ function attachInput(canvas, runtime, world) {
142
192
  time: performance.now(),
143
193
  moved: false,
144
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);
145
198
  canvas.setPointerCapture(event.pointerId);
146
199
  };
147
200
  const onPointerMove = (event) => {
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
+ }
148
208
  const p = pointers.get(event.pointerId);
149
209
  if (!p) return;
150
210
  const dx = event.clientX - p.x;
@@ -161,8 +221,11 @@ function attachInput(canvas, runtime, world) {
161
221
  move.active = true;
162
222
  move.x = nx * scale;
163
223
  move.y = ny * scale;
224
+ if (runtime.maxFps > 0) latch.stick = { x: move.x, y: move.y };
164
225
  };
165
226
  const onPointerUp = (event) => {
227
+ if (orbit?.busy && orbit.up(event)) return;
228
+ orbit?.pointer(event);
166
229
  const p = pointers.get(event.pointerId);
167
230
  pointers.delete(event.pointerId);
168
231
  if (stickId === event.pointerId) clearStick();
@@ -183,6 +246,7 @@ function attachInput(canvas, runtime, world) {
183
246
  canvas.removeEventListener('pointermove', onPointerMove);
184
247
  canvas.removeEventListener('pointerup', onPointerUp);
185
248
  canvas.removeEventListener('pointercancel', onPointerUp);
249
+ orbit?.detach();
186
250
  };
187
251
  }
188
252
 
@@ -194,27 +258,51 @@ function attachResize(canvas, world) {
194
258
  return () => observer.disconnect();
195
259
  }
196
260
 
197
- function startLoop(runtime, world, sprites, hudRefs, onFirstFrame, onError) {
261
+ function startLoop(runtime, world, sprites, hudRefs, onFirstFrame, onError, latch) {
198
262
  let raf = 0;
199
- let previousTime = performance.now();
263
+ const clock = makeFrameClock(performance.now());
200
264
  let firstFrameSignaled = false;
201
265
  const tick = (now) => {
202
- const dt = Math.min(0.033, (now - previousTime) / 1000);
203
- 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
+ }
204
275
  try {
205
- 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
+ }
206
286
  // A behavior may have requested a scene switch; apply it here, between
207
287
  // frames, never mid physics dispatch. The load resets
208
288
  // registered systems -- the rapier world frees and lazily rebuilds --
209
289
  // while `runtime.persistent` carries the player's cross-scene state.
210
290
  if (runtime.requestedScene) {
211
- const next = loadRequestedScene(runtime);
291
+ const next = world.emptyNodesOwned
292
+ ? loadEmptyScene(world, runtime, loadRequestedScene)
293
+ : loadRequestedScene(runtime);
294
+ if (runtime.skipsEmptyNodes) prepareEmptyNodes(world, runtime);
212
295
  runtime.currentScenePath = next;
213
296
  runtime.persistent.sceneChangeGraceUntil = runtime.time + 1;
214
297
  }
215
298
  syncActors(world, runtime, runtime.sprites ?? sprites, dt);
216
299
  if (world.debugLines.visible) updatePhysicsDebug(world, runtime.physics3d?.debugRender());
217
- 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);
218
306
  updateHud(runtime, hudRefs);
219
307
  } catch (err) {
220
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
+ }