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
@@ -1,3 +1,4 @@
1
+ import { animationDt } from './animationBudget';
1
2
  // The three.js side of the kit: renderer, lighting rig, ground, and per-actor
2
3
  // nodes built from Shape components. Values follow the vase reference rig --
3
4
  // hemisphere + ambient + one tuned shadow-casting directional, PCFSoft shadows,
@@ -17,16 +18,23 @@ import {
17
18
  import { parseModelCached, buildModelNode, modelArtSignature, animateModelParts } from './pxmodel';
18
19
  import { animateMotion } from './motion';
19
20
  import { modelRefSignature } from './modelrefs';
20
- import { lookIsEnabled } from './look';
21
+ import { lookIsEnabled, bakingLater } from './look';
22
+ import { makeLookBake, stepLookBake, orderLookBake, clearLookBake } from './lookbake';
21
23
  import { artReady } from '@imports/castle.physics-2d/engine/art';
22
- import { ActorNode } from './actornode.js';
23
- import { remember, sameAs, recordReads } from './unchanged.js';
24
+ import { ActorNode, freezeWhenUnchanged, subtreeIsAsRecorded } from './actornode.js';
25
+ import { EMPTY_PASS_ABORTED, checkEmptyPass, updateEmptyNode, syncEmptyNodes, forgetEmptyNodes, releaseEmptyNode, watchEmptyNode, freezeEmptyNode } from './emptynodes.js';
26
+ import { remember, sameAs, recordReads, noteChangedStill } from './unchanged.js';
24
27
  import { renderWithNearShadows, dropNearShadows } from './nearshadows.js';
28
+ import { fitOrbitLens, giveBackOrbitLens } from './orbitlens.js';
29
+ import { fitViewRange, giveBackViewRange } from './viewrange.js';
30
+ import { renderWithSky, leaveSky, skyHorizonColor } from './sky.js';
31
+ import { holdShadowFade, renderShadowFaded, dropShadowFade } from './shadowfade.js';
25
32
  import {
26
33
  takeModel,
27
34
  releaseModel,
28
35
  copyModel,
29
36
  isStaticModel,
37
+ dropEmptyGroups,
30
38
  makeInstances,
31
39
  drawInstances,
32
40
  aimInstances,
@@ -103,6 +111,23 @@ export function makeWorld3D(canvas) {
103
111
  // (nearshadows.js): the shadow the engine draws for them, which is its
104
112
  // own; the sun's is never written.
105
113
  nearShadows: null,
114
+ // For scenes that set `"engine": { "sky": { ... } }` (sky.js): the sky's
115
+ // mesh, textures and fade. null unless such a scene is playing.
116
+ sky: null,
117
+ // For scenes that set `"engine": { "camera": { "follow": "rigid",
118
+ // "control": "orbit" } }` (orbitlens.js): the lens the camera had before
119
+ // the key, given back when the keyed scene goes. And for scenes with
120
+ // that key and `"shadows": { "distance": n }` (shadowfade.js): the
121
+ // world's own variants of the materials the near shadows fade out on.
122
+ orbitLens: null,
123
+ shadowFade: null,
124
+ // For scenes that set `"engine": { "look": { "bake": "deferred" } }`
125
+ // (lookbake.js): whether the scene now playing is one, and the queue of
126
+ // what is still to bake, made when the first model is built for such a
127
+ // scene. `lookBake.shown` is true once a frame has been drawn with
128
+ // nothing left to bake.
129
+ bakesLookLater: false,
130
+ lookBake: null,
106
131
  instances: new Map(),
107
132
  instanceModels: false,
108
133
  debugLines,
@@ -112,12 +137,19 @@ export function makeWorld3D(canvas) {
112
137
  }
113
138
 
114
139
  export function updatePhysicsDebug(world, buffers) {
115
- if (!buffers) return;
116
- const geometry = new THREE.BufferGeometry();
117
- geometry.setAttribute('position', new THREE.BufferAttribute(buffers.vertices, 3));
118
- geometry.setAttribute('color', new THREE.BufferAttribute(buffers.colors, 4));
119
- world.debugLines.geometry.dispose();
120
- world.debugLines.geometry = geometry;
140
+ try {
141
+ if (!buffers) return;
142
+ // Geometry disposal can run listeners outside an actor pass.
143
+ outsideCall(world, () => {
144
+ const geometry = new THREE.BufferGeometry();
145
+ geometry.setAttribute('position', new THREE.BufferAttribute(buffers.vertices, 3));
146
+ geometry.setAttribute('color', new THREE.BufferAttribute(buffers.colors, 4));
147
+ world.debugLines.geometry.dispose();
148
+ world.debugLines.geometry = geometry;
149
+ });
150
+ } catch (error) {
151
+ if (error !== EMPTY_PASS_ABORTED) throw error;
152
+ }
121
153
  }
122
154
 
123
155
  function addLights(scene) {
@@ -163,24 +195,38 @@ function addGround(scene) {
163
195
  // world size of one texture repeat (meters). The line grid only shows on the
164
196
  // untextured ground -- over art it reads as noise.
165
197
  export function syncGround(world, setting, sprites) {
198
+ try {
199
+ dressGround(world, setting, sprites);
200
+ } catch (error) {
201
+ if (error !== EMPTY_PASS_ABORTED) throw error;
202
+ }
203
+ }
204
+
205
+ // Actor passes use the throwing implementation so invalidation stops the
206
+ // pass; a deck calling syncGround gets control back without our sentinel.
207
+ function dressGround(world, setting, sprites) {
166
208
  const sig = `${JSON.stringify(setting ?? null)}|${artRefSignature(setting?.art, sprites)}`;
167
209
  if (sig === world.groundSig) return;
168
- const tile = setting?.tile > 0 ? setting.tile : 2;
169
- const repeat = [GROUND_SIZE / tile, GROUND_SIZE / tile];
170
- const texture = setting?.art ? resolveArtTexture(setting.art, sprites, repeat) : null;
171
- world.groundSig = sig;
172
- const material = new THREE.MeshStandardMaterial({
173
- color: new THREE.Color(setting?.color ?? (texture ? '#ffffff' : '#22222b')),
174
- map: texture,
175
- dithering: true,
210
+ // Also callable outside an actor pass: the old material runs listeners.
211
+ outsideCall(world, () => {
212
+ const tile = setting?.tile > 0 ? setting.tile : 2;
213
+ const repeat = [GROUND_SIZE / tile, GROUND_SIZE / tile];
214
+ const texture = setting?.art ? resolveArtTexture(setting.art, sprites, repeat) : null;
215
+ world.groundSig = sig;
216
+ const material = new THREE.MeshStandardMaterial({
217
+ color: new THREE.Color(setting?.color ?? (texture ? '#ffffff' : '#22222b')),
218
+ map: texture,
219
+ dithering: true,
220
+ });
221
+ world.ground.material.dispose();
222
+ if (world.emptyPass) checkEmptyPass(world);
223
+ world.ground.material = material;
224
+ // `"none": true`: no ground at all, drawn or stood on (the physics system
225
+ // leaves its collider out too).
226
+ const none = setting?.none === true;
227
+ world.ground.visible = !none;
228
+ world.grid.visible = !texture && !none;
176
229
  });
177
- world.ground.material.dispose();
178
- world.ground.material = material;
179
- // `"none": true`: no ground at all, drawn or stood on (the physics system
180
- // leaves its collider out too).
181
- const none = setting?.none === true;
182
- world.ground.visible = !none;
183
- world.grid.visible = !texture && !none;
184
230
  }
185
231
 
186
232
  // The signature suffix for an actor's Model component: the model file's text
@@ -199,12 +245,13 @@ function actorModelSig(actor, sprites, files) {
199
245
  // Build / refresh the node for one actor. Rebuilds only when what it looks
200
246
  // like (Shape / Model / their art) changes. A Model replaces the Shape's own
201
247
  // mesh with the .pxmodel rig; the Shape still sizes the physics collider.
202
- function ensureActorNode(world, actor, sprites, files) {
248
+ function ensureActorNode(world, actor, sprites, files, drops) {
203
249
  const modelSig = actorModelSig(actor, sprites, files);
204
- const sig = nodeSignature(actor, sprites, modelSig);
250
+ const sig = builtAs(drops, nodeSignature(actor, sprites, modelSig));
205
251
  let entry = world.nodes.get(actor.id);
206
252
  if (entry && entry.sig !== sig) {
207
253
  releaseActorNode(world, entry);
254
+ if (world.emptyPass) checkEmptyPass(world);
208
255
  entry = null;
209
256
  }
210
257
  if (!entry) {
@@ -218,24 +265,44 @@ function ensureActorNode(world, actor, sprites, files) {
218
265
  addModelRig(world, entry, model, modelComponent, `${modelComponent.file}|${modelSig}`, {
219
266
  sprites,
220
267
  files,
268
+ drops,
221
269
  });
222
270
  } else if (shape) {
223
271
  node.add(makeShapeMesh(shape, sprites));
224
272
  }
225
- world.scene.add(node);
226
- world.nodes.set(actor.id, entry);
273
+ if (world.emptyPass) {
274
+ attachEmptyActor(world, actor.id, entry);
275
+ } else {
276
+ world.scene.add(node);
277
+ world.nodes.set(actor.id, entry);
278
+ }
227
279
  }
228
280
  return entry;
229
281
  }
230
282
 
283
+ // Ownership precedes attachment only in the keyed mode: an attachment
284
+ // listener can dispose the world before scene.add has returned.
285
+ function attachEmptyActor(world, id, entry) {
286
+ checkEmptyPass(world);
287
+ world.nodes.set(id, entry);
288
+ watchEmptyNode(world, entry);
289
+ world.scene.add(entry.node);
290
+ checkEmptyPass(world);
291
+ }
292
+
231
293
  // The actor's model, from the shared build of it: a copy of its own, or,
232
294
  // for a static model in the player, a place among that model's instances.
233
- function addModelRig(world, entry, model, modelComponent, key, { sprites, files }) {
295
+ function addModelRig(world, entry, model, modelComponent, key, { sprites, files, drops }) {
234
296
  const file = modelComponent.file;
297
+ if (drops === true) key = `${key}|dropEmptyParts`;
235
298
  entry.modelKey = key;
236
- const template = takeModel(world.models, key, () =>
237
- buildModelNode(model, sprites, files, file, [file], { optimize: true })
238
- );
299
+ const build = () => buildModelNode(model, sprites, files, file, [file], { optimize: true });
300
+ const template = takeModel(world.models, key, world.bakesLookLater ? () => buildBakingLater(world, key, build) : build);
301
+ if (drops === true && withoutEmptyParts(template, model).children.length === 0) {
302
+ // A model that draws nothing has no rig; `modelParts` is there and empty.
303
+ entry.node.userData.modelParts = new Map();
304
+ return;
305
+ }
239
306
  const instanced = world.instanceModels && isStaticModel(template);
240
307
  const rig = instanced ? new THREE.Group() : copyModel(template);
241
308
  rig.position.y = modelComponent.yOffset ?? 0;
@@ -252,9 +319,63 @@ function addModelRig(world, entry, model, modelComponent, key, { sprites, files
252
319
  }
253
320
  }
254
321
 
322
+ //
323
+ // Scenes that set `"engine": { "dropEmptyParts": true }`
324
+ //
325
+ // A game build merges a model's meshes into a few draw calls and leaves the
326
+ // group of every part standing, most of them now empty; a town's scene is two
327
+ // thirds such groups, each visited by three.js and by the engine on every
328
+ // frame. For a scene that asks, a placed model is built without the groups
329
+ // that draw nothing (optimize.js `dropEmptyGroups` has what goes and what
330
+ // always stays), and an actor whose model draws nothing at all gets no rig
331
+ // under its node. CLAUDE.md has the terms.
332
+ //
333
+ // With the key absent nothing here runs but the tests of `drops`: a node's
334
+ // signature, a shared build's key and the build are what they were. With it,
335
+ // the signature and the key say so, so that a node or a build made for a
336
+ // scene that asked is never one for a scene that did not, in either
337
+ // direction: the nodes of a resident scene parked while another plays, a pack
338
+ // mounted in a town, a door trip, a scene file reloaded with the key changed.
339
+ //
340
+ // Whether a pass drops is the pass's own: `syncActors` reads it once from the
341
+ // runtime it was handed and passes it down (`drops`) to everything that makes
342
+ // a signature or a build. Nothing about it is kept on the world, so a pass
343
+ // entered from inside another (a callback that syncs another scene), one that
344
+ // throws, or a dispose, cannot change what the pass around it builds. What is
345
+ // kept says which way it was made and is only ever matched against the pass
346
+ // asking: a node's `sig`, a shared build's key (and so `world.instances`,
347
+ // keyed the same), and what a skipping pass wrote down (`builtFrom.drops`).
348
+
349
+ // The shared builds whose empty groups have been taken out.
350
+ const withoutEmpty = new WeakSet();
351
+
352
+ // `template`, a shared build made for such a scene, with its empty groups
353
+ // gone: taken out once, when the build is first placed.
354
+ function withoutEmptyParts(template, model) {
355
+ if (!withoutEmpty.has(template)) {
356
+ withoutEmpty.add(template);
357
+ dropEmptyGroups(template, model);
358
+ }
359
+ return template;
360
+ }
361
+
362
+ // A node's signature, saying which way it was built.
363
+ function builtAs(drops, sig) {
364
+ return drops === true ? `${sig}|dropEmptyParts` : sig;
365
+ }
366
+
367
+ // `build`, for a scene that asked for its models' look to be baked after they
368
+ // are drawn (lookbake.js): the baking is queued on the world as this model's.
369
+ function buildBakingLater(world, key, build) {
370
+ if (world.disposed === true) return build();
371
+ world.lookBake ??= makeLookBake();
372
+ return bakingLater(world.lookBake, key, build);
373
+ }
374
+
255
375
  // Removes an actor's node. A shared model build is given back rather than
256
376
  // disposed, since other actors may still draw it.
257
377
  function releaseActorNode(world, entry) {
378
+ if (world.emptyNodes) releaseEmptyNode(world, entry.node);
258
379
  world.scene.remove(entry.node);
259
380
  if (!entry.modelKey) {
260
381
  disposeNode(entry.node);
@@ -277,9 +398,85 @@ const DEG = Math.PI / 180;
277
398
  // actors come and go. Dynamic bodies leave an exact quaternion in
278
399
  // `actor.runtime.quat`; everything else rotates by the Transform's euler
279
400
  // degrees.
401
+ // Worlds that never asked do not enter any empty-node lifecycle helpers.
280
402
  export function syncActors(world, runtime, sprites, dt = 0) {
403
+ try {
404
+ if (world.emptyNodesOwned) {
405
+ const state = world.emptyNodes;
406
+ if (world.disposed || world.emptyNodesBlocked || (world.emptyPass && state !== world.emptyPass)) return;
407
+ if (state && state.runtime === runtime) {
408
+ syncActorsWithEmptyNodes(world, runtime, sprites, dt, state);
409
+ return;
410
+ }
411
+ }
412
+ // A world that has held actors still, or a scene that asks to
413
+ // (`"engine": { "staticActors": true }`): the same pass, whatever its kind,
414
+ // seen in and out by the world's keeper (`syncActorsKept`, below).
415
+ if (world.stillKeeper || runtime.keepsStaticActors === true) {
416
+ syncActorsKept(world, runtime, sprites, dt);
417
+ return;
418
+ }
419
+ // Every other pass is counted while it runs, and that is all: nothing on a
420
+ // world without a keeper reads the count. It is what tells a keeper made
421
+ // from inside this pass (a callback that syncs a scene that asks) that a
422
+ // pass it never saw enter is running around it.
423
+ world.unkept = (world.unkept ?? 0) + 1;
424
+ try {
425
+ syncActorsAsEver(world, runtime, sprites, dt);
426
+ } finally {
427
+ world.unkept -= 1;
428
+ }
429
+ } catch (error) {
430
+ if (error !== EMPTY_PASS_ABORTED) throw error;
431
+ }
432
+ }
433
+
434
+ // Only the active mode pays for the bracket and chooses detached placement.
435
+ function syncActorsWithEmptyNodes(world, runtime, sprites, dt, state) {
436
+ if (state.dispatchDepth || state.draining) return;
437
+ const previous = world.emptyPass;
438
+ world.emptyPass = state;
439
+ state.depth += 1;
440
+ try {
441
+ if (state.depth === 1) syncEmptyNodes(world, state);
442
+ checkEmptyPass(world, state);
443
+ if (world.stillKeeper || runtime.keepsStaticActors === true) {
444
+ syncActorsKept(world, runtime, sprites, dt, placeEmptyActor);
445
+ } else {
446
+ world.unkept = (world.unkept ?? 0) + 1;
447
+ try { syncActorsAsEver(world, runtime, sprites, dt, placeEmptyActor); }
448
+ finally { world.unkept -= 1; }
449
+ }
450
+ } catch (error) {
451
+ if (error !== EMPTY_PASS_ABORTED) throw error;
452
+ } finally {
453
+ state.depth -= 1;
454
+ if (previous) world.emptyPass = previous;
455
+ else delete world.emptyPass;
456
+ }
457
+ }
458
+
459
+ // `syncActors` as it always was.
460
+ function animateActor(world, entry, dt, actor) {
461
+ const elapsed = animationDt(entry, dt);
462
+ if (elapsed === null) return;
463
+ animateModelParts(entry, elapsed, world.emptyPass ? world : undefined);
464
+ if (world.emptyPass) checkEmptyPass(world);
465
+ animateMotion(entry, elapsed, actor, world.emptyPass ? world : undefined);
466
+ if (world.emptyPass) checkEmptyPass(world);
467
+ }
468
+
469
+ // Only an opted-in, detached actor with an existing node may sleep.
470
+ // The controller checks its live Transform and wakes it before return.
471
+ function renderActorSleeps(world, actor) {
472
+ return actor.runtime?.renderSleep === true && world.nodes.has(actor.id) && !world.nodes.get(actor.id).node.parent;
473
+ }
474
+
475
+ function syncActorsAsEver(world, runtime, sprites, dt, place = placeActor) {
476
+ const drops = runtime.dropsEmptyParts === true;
477
+ world.bakesLookLater = runtime.bakesLookLater === true;
281
478
  if (runtime.skipsUnchangedActors === true && world.disposed !== true) {
282
- syncActorsSkipping(world, runtime, sprites, dt);
479
+ syncActorsSkipping(world, runtime, sprites, dt, drops, place);
283
480
  return;
284
481
  }
285
482
  if (world.skipping.on) stopSkipping(world);
@@ -289,25 +486,23 @@ export function syncActors(world, runtime, sprites, dt = 0) {
289
486
  const key = runtime.sceneKey ?? runtime.scenePath;
290
487
  if (key !== world.scenePath) {
291
488
  swapSceneNodes(world, key, runtime.residentScenes);
489
+ if (world.emptyPass) checkEmptyPass(world);
292
490
  }
293
- syncGround(world, runtime.data?.ground, sprites);
491
+ dressGround(world, runtime.data?.ground, sprites);
492
+ if (world.emptyPass) checkEmptyPass(world);
294
493
  const seen = new Set();
295
494
  for (const actor of runtime.getActors()) {
296
495
  const t = actor.components.Transform;
297
496
  if (!t) continue;
298
497
  seen.add(actor.id);
299
- const entry = ensureActorNode(world, actor, sprites, runtime.files);
300
- const node = entry.node;
301
- node.position.set(t.x, t.y, t.z);
302
- const quat = actor.runtime?.quat;
303
- if (quat) node.quaternion.set(quat.x, quat.y, quat.z, quat.w);
304
- else node.rotation.set(t.rotationX * DEG, t.rotationY * DEG, t.rotationZ * DEG);
305
- animateModelParts(entry, dt);
306
- animateMotion(entry, dt, actor);
498
+ if (renderActorSleeps(world, actor)) continue;
499
+ const entry = place(world, actor, t, sprites, runtime.files, undefined, drops);
500
+ animateActor(world, entry, dt, actor);
307
501
  }
308
502
  for (const [id, entry] of world.nodes) {
309
503
  if (seen.has(id)) continue;
310
504
  releaseActorNode(world, entry);
505
+ if (world.emptyPass) checkEmptyPass(world);
311
506
  world.nodes.delete(id);
312
507
  }
313
508
  if (world.instances.size > 0) {
@@ -334,9 +529,12 @@ function swapSceneNodes(world, path, resident) {
334
529
  // An instanced rig is drawn by its model's shared instances wherever
335
530
  // its node is; parking it would leave it drawn in the next scene.
336
531
  releaseActorNode(world, entry);
532
+ if (world.emptyPass) checkEmptyPass(world);
337
533
  continue;
338
534
  }
535
+ if (world.emptyNodes) releaseEmptyNode(world, entry.node);
339
536
  world.scene.remove(entry.node);
537
+ if (world.emptyPass) checkEmptyPass(world);
340
538
  parked.set(id, entry);
341
539
  }
342
540
  world.parked.set(world.scenePath, parked);
@@ -350,13 +548,19 @@ function swapSceneNodes(world, path, resident) {
350
548
  for (const [id, entry] of back) {
351
549
  const current = world.nodes.get(id);
352
550
  if (current) releaseActorNode(world, current);
353
- world.scene.add(entry.node);
354
- world.nodes.set(id, entry);
551
+ if (world.emptyPass) attachEmptyActor(world, id, entry);
552
+ else {
553
+ world.scene.add(entry.node);
554
+ world.nodes.set(id, entry);
555
+ }
355
556
  }
356
557
  }
357
558
  for (const [parkedPath, parked] of world.parked) {
358
559
  if (!keep.has(parkedPath)) {
359
- for (const entry of parked.values()) releaseActorNode(world, entry);
560
+ for (const entry of parked.values()) {
561
+ releaseActorNode(world, entry);
562
+ if (world.emptyPass) checkEmptyPass(world);
563
+ }
360
564
  world.parked.delete(parkedPath);
361
565
  }
362
566
  }
@@ -364,28 +568,117 @@ function swapSceneNodes(world, path, resident) {
364
568
  }
365
569
 
366
570
  export function resizeWorld(world, width, height) {
367
- world.renderer.setSize(width, height, false);
368
- world.composer.setSize(width, height);
369
- world.camera.aspect = width / Math.max(1, height);
370
- world.camera.updateProjectionMatrix();
571
+ try {
572
+ // Resizing the composer can dispose its render targets.
573
+ outsideCall(world, () => {
574
+ world.renderer.setSize(width, height, false);
575
+ world.composer.setSize(width, height);
576
+ world.camera.aspect = width / Math.max(1, height);
577
+ world.camera.updateProjectionMatrix();
578
+ });
579
+ } catch (error) {
580
+ if (error !== EMPTY_PASS_ABORTED) throw error;
581
+ }
371
582
  }
372
583
 
373
584
  // `runtime` is given by the player, whose scene may have asked for shadows
374
585
  // near the view only (`"engine": { "shadows": { "distance": n } }`,
375
586
  // nearshadows.js). The editors give none and draw every scene the one way.
376
587
  export function renderWorld(world, runtime) {
588
+ try {
589
+ // A scene that set `"engine": { "sky": { ... } }` (sky.js), or a world with
590
+ // something left from one that did: the same frame, with the sky in the
591
+ // scene graph for as long as it takes to draw. Otherwise the frame as it
592
+ // always was.
593
+ if (runtime?.sky || world.sky) {
594
+ renderWithSky(world, runtime, drawFrame, performance.now(), skyCallFor);
595
+ } else drawFrame(world, runtime);
596
+ } catch (error) {
597
+ if (error !== EMPTY_PASS_ABORTED) throw error;
598
+ }
599
+ }
600
+
601
+ // Acquired only when the sky makes a record, not on an unowned or disposed
602
+ // world's keyed frame. A later record reuses the same callback.
603
+ function skyCallFor(world) {
604
+ return (world.skyCall ??= (fn) => outsideCall(world, fn));
605
+ }
606
+
607
+ function drawFrame(world, runtime) {
608
+ const fade = orbitFrame(world, runtime);
377
609
  // A world with nothing of the mode's, whose scene did not ask (or which is
378
610
  // being disposed): the two statements this function always was.
379
611
  const distance = runtime?.nearShadowDistance ?? 0;
380
612
  if (!world.nearShadows && !(distance > 0 && world.disposed !== true)) {
381
613
  drawWorld(world);
382
- return;
614
+ } else if (fade) {
615
+ renderShadowFaded(fade, () => drawNear(world, distance, fade));
616
+ } else {
617
+ drawNear(world, distance);
618
+ }
619
+ // Only a world that has built a model for a scene that set
620
+ // `"engine": { "look": { "bake": "deferred" } }` has anything here.
621
+ if (world.lookBake) bakeLooks(world);
622
+ }
623
+
624
+ // A little of the baking such a scene's models are waiting for, now that the
625
+ // frame is drawn (lookbake.js). Models nearest the camera come first, by where
626
+ // the actors placing them stood when the queue last grew. With nothing
627
+ // pending, the step only notes that the frame just drawn is the complete
628
+ // picture (`queue.shown`).
629
+ function bakeLooks(world) {
630
+ const queue = world.lookBake;
631
+ if (world.disposed === true) return;
632
+ if (queue.pending > 0 && queue.unsorted && queue.drawn) {
633
+ const nearest = new Map();
634
+ for (const entry of world.nodes.values()) {
635
+ if (!entry.modelKey) continue;
636
+ const distance = entry.node.position.distanceToSquared(world.camera.position);
637
+ if (!(distance >= nearest.get(entry.modelKey))) nearest.set(entry.modelKey, distance);
638
+ }
639
+ orderLookBake(queue, (key) => nearest.get(key) ?? Number.MAX_VALUE);
383
640
  }
641
+ stepLookBake(queue);
642
+ }
643
+
644
+ // The orbit camera key's lens (orbitlens.js), on each frame of a keyed
645
+ // scene. An editor's frame (no runtime) of a world that played one gives the
646
+ // lens back. A frame of a keyless scene never looks at the camera: a load gave
647
+ // the lens back before that scene's code ran. With near shadows as well, the
648
+ // frames the near-shadow mode draws fade its far edge out (shadowfade.js, the
649
+ // fade returned); any other frame of a world that had the fade drops it.
650
+ function orbitFrame(world, runtime) {
651
+ let fade = null;
652
+ // The sky has stepped before drawFrame, so its current fade colours are
653
+ // available here. Invalid/absent view keys do not acquire any state.
654
+ if (runtime) fitViewRange(world, runtime, THREE.Fog, skyHorizonColor);
655
+ else if (world.viewRange) outsideCall(world, () => giveBackViewRange(world));
656
+ if (runtime?.cameraControl === 'orbit') {
657
+ if (world.disposed !== true) {
658
+ // Made at load (Scene3DPlayer, physics-2d's SceneRuntime.load); here
659
+ // too for a physics-2d pinned from before that, whose later loads do
660
+ // not make it. An own name tag registers on its next frame.
661
+ world.ownModelWith ??= new Set();
662
+ fitOrbitLens(world, runtime);
663
+ fade = holdShadowFade(world, runtime);
664
+ }
665
+ } else if (!runtime && world.orbitLens) {
666
+ outsideCall(world, () => giveBackOrbitLens(world));
667
+ }
668
+ if (!fade && world.shadowFade) outsideCall(world, () => dropShadowFade(world));
669
+ return fade;
670
+ }
671
+
672
+ // A frame through the near-shadow mode (nearshadows.js), faded or not.
673
+ function drawNear(world, distance, fade) {
384
674
  renderWithNearShadows(
385
675
  world,
386
676
  distance,
387
677
  () => fitShadowBias(world),
388
- () => world.composer.render()
678
+ () => world.composer.render(),
679
+ // Made once per world; unchanged frames neither call nor allocate it.
680
+ (world.nearShadowCall ??= (fn) => outsideCall(world, fn)),
681
+ fade
389
682
  );
390
683
  }
391
684
 
@@ -418,24 +711,56 @@ function fitShadowBias(world) {
418
711
  }
419
712
 
420
713
  export function disposeWorld(world) {
421
- // Releasing a node runs `dispose` listeners, which may sync this world
422
- // again. From here on it never skips (`syncActors` reads `disposed`), so
423
- // such a sync writes nothing down; what was written down before goes now,
424
- // and again after the listeners have run, whether or not one throws.
425
- world.disposed = true;
426
- // A `dispose` listener on the near-shadow mode's map that throws does not
427
- // keep the rest from being released.
428
714
  try {
429
- dropNearShadows(world);
430
- } finally {
431
- disposeNodes(world);
715
+ // Releasing a node runs `dispose` listeners, which may sync this world
716
+ // again. From here on it never skips (`syncActors` reads `disposed`), so
717
+ // such a sync writes nothing down; what was written down before goes now,
718
+ // and again after the listeners have run, whether or not one throws.
719
+ world.disposed = true;
720
+ // With no keeper this is counted by `unkept`, just like a plain sync.
721
+ outsideCall(world, () => {
722
+ // Every cleanup runs even when an earlier one throws. Keep the first
723
+ // thrown value (including a falsy one) through all five stages.
724
+ let first = null;
725
+ const clean = (fn) => {
726
+ try { fn(); } catch (err) { first ??= { err }; }
727
+ };
728
+ try {
729
+ clean(() => giveBackOrbitLens(world));
730
+ if (world.viewRange) clean(() => giveBackViewRange(world));
731
+ } finally {
732
+ try {
733
+ // The sky's record (skylife.js): disposed now, or by the frame in
734
+ // progress on its way out; a `dispose` listener's error comes back.
735
+ clean(() => {
736
+ const failed = world.sky ? leaveSky(world) : null;
737
+ if (failed !== null) throw failed;
738
+ });
739
+ } finally {
740
+ try {
741
+ clean(() => dropShadowFade(world));
742
+ } finally {
743
+ try {
744
+ clean(() => dropNearShadows(world));
745
+ } finally {
746
+ clean(() => disposeNodes(world));
747
+ }
748
+ }
749
+ }
750
+ }
751
+ if (first !== null) throw first.err;
752
+ });
753
+ } catch (error) {
754
+ if (error !== EMPTY_PASS_ABORTED) throw error;
432
755
  }
433
756
  }
434
757
 
435
758
  function disposeNodes(world) {
759
+ if (world.emptyNodesOwned) forgetEmptyNodes(world);
436
760
  world.skipping.on = false;
437
761
  leavingTheEngine(world);
438
762
  forgetEverything(world);
763
+ if (world.lookBake) clearLookBake(world.lookBake);
439
764
  try {
440
765
  for (const entry of world.nodes.values()) releaseActorNode(world, entry);
441
766
  world.nodes.clear();
@@ -533,6 +858,9 @@ const MODEL_SIGS_LIMIT = 512;
533
858
  // that is not the engine's. See the list above.
534
859
  function leavingTheEngine(world) {
535
860
  world.generation += 1;
861
+ // And nothing is frozen while code that is not the engine's runs inside a
862
+ // pass (only a world that holds actors still has anything here).
863
+ if (world.stillKeeper) dropStill(world);
536
864
  }
537
865
 
538
866
  // The scene now playing did not ask: every node is a plain Group again and
@@ -553,6 +881,7 @@ function forgetSnapshots(world) {
553
881
  // And what each node, playing or parked, remembers of its own matrices.
554
882
  function forgetEverything(world) {
555
883
  forgetSnapshots(world);
884
+ if (world.stillKeeper) dropStill(world);
556
885
  const forget = (entry) => {
557
886
  if (entry.node.computedFrom) entry.node.computedFrom = null;
558
887
  };
@@ -560,7 +889,7 @@ function forgetEverything(world) {
560
889
  for (const parked of world.parked.values()) parked.forEach(forget);
561
890
  }
562
891
 
563
- function syncActorsSkipping(world, runtime, sprites, dt) {
892
+ function syncActorsSkipping(world, runtime, sprites, dt, drops, place = placeActor) {
564
893
  // Entered while a pass is running: that pass is no longer alone.
565
894
  if (world.syncDepth > 0) leavingTheEngine(world);
566
895
  const outermost = world.syncDepth === 0;
@@ -569,7 +898,7 @@ function syncActorsSkipping(world, runtime, sprites, dt) {
569
898
  world.syncDepth += 1;
570
899
  let finished = false;
571
900
  try {
572
- skippingPass(world, runtime, sprites, dt, outermost ? started : -1);
901
+ skippingPass(world, runtime, sprites, dt, outermost ? started : -1, drops, undefined, place);
573
902
  finished = true;
574
903
  } finally {
575
904
  world.syncDepth -= 1;
@@ -579,20 +908,25 @@ function syncActorsSkipping(world, runtime, sprites, dt) {
579
908
 
580
909
  // One pass. `started` is the generation it may trust its state at; a pass
581
910
  // entered inside another is given one that never matches.
582
- function skippingPass(world, runtime, sprites, dt, started) {
911
+ function skippingPass(world, runtime, sprites, dt, started, drops, pass, place = placeActor) {
583
912
  beginPass(world, runtime, sprites);
913
+ if (world.emptyPass) checkEmptyPass(world);
584
914
  if (world.generation === started) {
585
915
  world.syncCount += 1;
586
916
  world.sigEpoch += 1;
587
917
  }
918
+ if (pass !== undefined) {
919
+ // `syncActorsHoldingStill`'s pass: settled, or ordinary from here.
920
+ if (staysSettled(world, runtime, sprites, started, drops, pass)) return settledPass(world, runtime, sprites, dt, started, drops, place);
921
+ }
588
922
  const seen = new Set();
589
923
  for (const actor of runtime.getActors()) {
590
924
  const t = actor.components.Transform;
591
925
  if (!t) continue;
592
926
  seen.add(actor.id);
593
- const entry = placeActor(world, actor, t, sprites, runtime.files, started);
594
- animateModelParts(entry, dt);
595
- animateMotion(entry, dt, actor);
927
+ if (renderActorSleeps(world, actor)) continue;
928
+ const entry = place(world, actor, t, sprites, runtime.files, started, drops);
929
+ animateActor(world, entry, dt, actor);
596
930
  }
597
931
  // While the pass was alone every actor seen has its node and no node was
598
932
  // released, so as many nodes as actors seen means no node has lost its actor.
@@ -612,11 +946,12 @@ function beginPass(world, runtime, sprites) {
612
946
  if (key !== world.scenePath) {
613
947
  leavingTheEngine(world);
614
948
  swapSceneNodes(world, key, runtime.residentScenes);
949
+ if (world.emptyPass) checkEmptyPass(world);
615
950
  }
616
951
  const setting = runtime.data?.ground;
617
952
  if (!groundIsDressed(world, setting, sprites)) {
618
953
  leavingTheEngine(world);
619
- syncGround(world, setting, sprites);
954
+ dressGround(world, setting, sprites);
620
955
  }
621
956
  if (typeof world.scene.userData.groundHeight === 'function' || world.instanceModels || world.instances.size > 0) {
622
957
  leavingTheEngine(world);
@@ -632,9 +967,10 @@ function groundIsDressed(world, setting, sprites) {
632
967
  // One actor's node, found or built, put where its Transform says, and ready
633
968
  // to be animated: the skipping way while the pass is alone, `syncActors`'s way
634
969
  // once it is not.
635
- function placeActor(world, actor, t, sprites, files, started) {
970
+ function placeActor(world, actor, t, sprites, files, started, drops) {
636
971
  const alone = world.generation === started;
637
- const entry = alone ? nodeFor(world, actor, sprites, files) : nodeAsMain(world, actor, sprites, files);
972
+ const entry = started === undefined ? ensureActorNode(world, actor, sprites, files, drops)
973
+ : alone ? nodeFor(world, actor, sprites, files, drops) : nodeAsMain(world, actor, sprites, files, drops);
638
974
  const node = entry.node;
639
975
  node.position.set(t.x, t.y, t.z);
640
976
  const quat = actor.runtime?.quat;
@@ -643,16 +979,47 @@ function placeActor(world, actor, t, sprites, files, started) {
643
979
  else node.rotation.set(t.rotationX * DEG, t.rotationY * DEG, t.rotationZ * DEG);
644
980
  // A node moved under something with a ground-height callback of its own,
645
981
  // which animating it is about to call.
646
- if (node.parent !== world.scene && typeof node.parent?.userData?.groundHeight === 'function') {
982
+ if (started !== undefined && node.parent !== world.scene && typeof node.parent?.userData?.groundHeight === 'function') {
647
983
  leavingTheEngine(world);
648
984
  }
649
985
  return entry;
650
986
  }
651
987
 
988
+ function placeEmptyActor(world, actor, transform, sprites, files, started, drops) {
989
+ const found = started === undefined ? ensureActorNode(world, actor, sprites, files, drops)
990
+ : world.generation === started ? nodeFor(world, actor, sprites, files, drops)
991
+ : nodeAsMain(world, actor, sprites, files, drops);
992
+ checkEmptyPass(world);
993
+ putEmptyActor(found.node, transform, actor.runtime?.quat,
994
+ world.generation === started ? snapshotOf(world, found) : null);
995
+ checkEmptyPass(world);
996
+ if (typeof found.node.parent?.userData?.groundHeight === 'function' && found.node.parent !== world.scene) leavingTheEngine(world);
997
+ return found;
998
+ }
999
+
1000
+ function putEmptyActor(node, t, quat, snapshot = null) {
1001
+ const detached = node.emptyDetached && !node.parent && node.children.length === 0;
1002
+ const p = node.position;
1003
+ const q = node.quaternion;
1004
+ const moved = detached && (!Object.is(p.x, t.x) || !Object.is(p.y, t.y) || !Object.is(p.z, t.z));
1005
+ // Direct consumer writes on empty detached roots are outside the contract.
1006
+ // Comparing the quaternion here covers both Euler and physics placement.
1007
+ const x = q.x, y = q.y, z = q.z, w = q.w;
1008
+ p.set(t.x, t.y, t.z);
1009
+ if (snapshot) turnNode(snapshot, node, t, quat);
1010
+ else if (quat) q.set(quat.x, quat.y, quat.z, quat.w);
1011
+ else {
1012
+ const rx = t.rotationX * DEG, ry = t.rotationY * DEG, rz = t.rotationZ * DEG;
1013
+ if (!detached || node.rotation.x !== rx || node.rotation.y !== ry || node.rotation.z !== rz) node.rotation.set(rx, ry, rz);
1014
+ }
1015
+ if (detached && (moved || !Object.is(q.x, x) || !Object.is(q.y, y) || !Object.is(q.z, z) || !Object.is(q.w, w))) updateEmptyNode(node);
1016
+ }
1017
+
652
1018
  function releaseUnseen(world, seen) {
653
1019
  for (const [id, entry] of world.nodes) {
654
1020
  if (seen.has(id)) continue;
655
1021
  releaseNode(world, entry);
1022
+ if (world.emptyPass) checkEmptyPass(world);
656
1023
  world.nodes.delete(id);
657
1024
  }
658
1025
  }
@@ -727,10 +1094,11 @@ function artReadsTheSame(artReads, sprites) {
727
1094
  // Whether the actor's node signature would come out as it did when `entry`
728
1095
  // last built it: the Shape and Model components read the same field for
729
1096
  // field, the art the Shape names is the same objects in the same state, and
730
- // the model file's signature is the same.
731
- function looksTheSame(world, entry, actor, sprites, files) {
1097
+ // the model file's signature is the same; and it was written down by a pass
1098
+ // that built the way this one does (`drops`).
1099
+ function looksTheSame(world, entry, actor, sprites, files, drops) {
732
1100
  const built = world.snapshots.get(entry)?.builtFrom;
733
- if (!built) return false;
1101
+ if (!built || built.drops !== drops) return false;
734
1102
  const components = actor.components;
735
1103
  const model = components.Model;
736
1104
  return (
@@ -745,20 +1113,21 @@ function looksTheSame(world, entry, actor, sprites, files) {
745
1113
  // same way, but only when `looksTheSame` cannot vouch for the node. A node
746
1114
  // that has to be built or released ends the pass's being alone first. What a
747
1115
  // kept node was built from is written down after the signature is compared.
748
- function nodeFor(world, actor, sprites, files) {
1116
+ function nodeFor(world, actor, sprites, files, drops) {
749
1117
  const entry = world.nodes.get(actor.id);
750
- if (entry && looksTheSame(world, entry, actor, sprites, files)) return entry;
1118
+ if (entry && looksTheSame(world, entry, actor, sprites, files, drops)) return entry;
751
1119
  const artReads = [];
752
1120
  const modelSig = modelSigOf(world, actor.components.Model?.file, sprites, files);
753
- const sig = nodeSignature(actor, recordReads(sprites, artReads), modelSig);
1121
+ const sig = builtAs(drops, nodeSignature(actor, recordReads(sprites, artReads), modelSig));
754
1122
  if (!entry || entry.sig !== sig) {
755
- return buildNode(world, entry, actor, sig, modelSig, sprites, files);
1123
+ return buildNode(world, entry, actor, sig, modelSig, sprites, files, drops);
756
1124
  }
757
1125
  snapshotOf(world, entry).builtFrom = {
758
1126
  shape: remember(actor.components.Shape),
759
1127
  model: remember(actor.components.Model),
760
1128
  artReads: withReadiness(artReads),
761
1129
  modelSig,
1130
+ drops,
762
1131
  };
763
1132
  return entry;
764
1133
  }
@@ -766,12 +1135,12 @@ function nodeFor(world, actor, sprites, files) {
766
1135
  // `ensureActorNode` as it is, for a pass that is not alone: the signature is
767
1136
  // built and compared, nothing is read from what was written down and nothing
768
1137
  // is written. The node is an ActorNode all the same.
769
- function nodeAsMain(world, actor, sprites, files) {
1138
+ function nodeAsMain(world, actor, sprites, files, drops) {
770
1139
  const modelSig = actorModelSig(actor, sprites, files);
771
- const sig = nodeSignature(actor, sprites, modelSig);
1140
+ const sig = builtAs(drops, nodeSignature(actor, sprites, modelSig));
772
1141
  const entry = world.nodes.get(actor.id);
773
1142
  if (entry && entry.sig === sig) return entry;
774
- return buildNode(world, entry, actor, sig, modelSig, sprites, files);
1143
+ return buildNode(world, entry, actor, sig, modelSig, sprites, files, drops);
775
1144
  }
776
1145
 
777
1146
  // What is written down for an entry, made on first use.
@@ -784,22 +1153,27 @@ function snapshotOf(world, entry) {
784
1153
  return snapshot;
785
1154
  }
786
1155
 
787
- function buildNode(world, old, actor, sig, modelSig, sprites, files) {
1156
+ function buildNode(world, old, actor, sig, modelSig, sprites, files, drops) {
788
1157
  leavingTheEngine(world);
789
1158
  if (old) releaseNode(world, old);
1159
+ if (world.emptyPass) checkEmptyPass(world);
790
1160
  const entry = { node: new ActorNode(world.skipping), sig };
791
1161
  entry.node.userData.actorId = actor.id;
792
- fillNode(world, entry, actor, modelSig, sprites, files);
793
- world.scene.add(entry.node);
794
- world.nodes.set(actor.id, entry);
1162
+ fillNode(world, entry, actor, modelSig, sprites, files, drops);
1163
+ if (world.emptyPass) {
1164
+ attachEmptyActor(world, actor.id, entry);
1165
+ } else {
1166
+ world.scene.add(entry.node);
1167
+ world.nodes.set(actor.id, entry);
1168
+ }
795
1169
  return entry;
796
1170
  }
797
1171
 
798
- function fillNode(world, entry, actor, modelSig, sprites, files) {
1172
+ function fillNode(world, entry, actor, modelSig, sprites, files, drops) {
799
1173
  const { Model: placed, Shape: shape } = actor.components;
800
1174
  const model = placed?.file ? parseModelCached(files?.[placed.file]) : null;
801
1175
  if (model) {
802
- addModelRig(world, entry, model, placed, `${placed.file}|${modelSig}`, { sprites, files });
1176
+ addModelRig(world, entry, model, placed, `${placed.file}|${modelSig}`, { sprites, files, drops });
803
1177
  } else if (shape) {
804
1178
  entry.node.add(makeShapeMesh(shape, sprites));
805
1179
  }
@@ -840,3 +1214,412 @@ function sameTurn(r, x, y, z) {
840
1214
  function sameQuaternion(q, was) {
841
1215
  return Object.is(q.x, was.x) && Object.is(q.y, was.y) && Object.is(q.z, was.z) && Object.is(q.w, was.w);
842
1216
  }
1217
+
1218
+ //
1219
+ // Scenes that set `"engine": { "staticActors": true }`
1220
+ //
1221
+ // With `skipUnchangedActors` a pass still asks, of every actor on every frame,
1222
+ // whether anything it is drawn from has changed. For scenery that never
1223
+ // changes, the asking is the cost. A scene that also sets `staticActors` marks
1224
+ // such actors in its file (`"static": true` on the actor), its runtime holds
1225
+ // them still (physics-2d engine/scene.js: `stillActors`, `stillVersion`,
1226
+ // `touch`), and this world leaves them out of its pass and freezes their nodes
1227
+ // (actornode.js). CLAUDE.md has the terms. The rule:
1228
+ //
1229
+ // A pass is ORDINARY (every actor, as the skipping pass above runs it)
1230
+ // unless the still set and the things its actors share read as they did
1231
+ // when the last ordinary pass that ended alone adopted them; then it is
1232
+ // SETTLED, and a still actor is left exactly as that pass left it.
1233
+ //
1234
+ // The still set is adopted only AFTER an ordinary pass has completed
1235
+ // without throwing. While any pass, or anything it calls back into, is
1236
+ // running, nothing is frozen and no still state is trusted. Any
1237
+ // interruption -- a throw, a pass entered from inside another, by this
1238
+ // runtime or any other -- leaves the next pass ordinary.
1239
+ //
1240
+ // The second paragraph is one mechanism, the same in the runtime's update,
1241
+ // here and in the physics system: a StillKeeper (physics-2d
1242
+ // engine/stillClock.js has it and the reasoning), handed out by the runtime
1243
+ // (`newStillKeeper`) and kept as `world.stillKeeper`. Nothing about an
1244
+ // adoption is kept anywhere else. What this world adds to it:
1245
+ // - the keeper counts an entry at the top of `syncActorsHoldingStill`,
1246
+ // before anything else; `dropStill` reports to it (`interrupt`) from
1247
+ // `leavingTheEngine`, which the engine calls before anything in a pass can
1248
+ // run code that is not its own (a node built or released, a scene change,
1249
+ // the ground dressed anew, a callback, a pass entered from inside
1250
+ // another), and from a frame without the key and a dispose;
1251
+ // - `thaw` moves `skipping.epoch`, which unfreezes every node at once: before
1252
+ // an ordinary pass visits its first actor, with every `dropStill`, and on
1253
+ // the way out of any pass that leaves nothing adopted. So a listener or
1254
+ // callback that walks the scene, draws it or syncs it from inside a pass,
1255
+ // settled or not, finds every node an ordinary ActorNode;
1256
+ // - the pass is `completed`, to the keeper, only if it was outermost,
1257
+ // returned, and was alone to its end by the generation; `adoptStill` is
1258
+ // what the keeper calls, last, when it will keep what it returns.
1259
+ //
1260
+ // What makes a pass that began settled ordinary (`staysSettled`), each asked
1261
+ // at its start, after `beginPass`, and never worked out afterwards:
1262
+ // - the keeper's count or the runtime's `stillVersion` has moved since the
1263
+ // pass began (the audit touched an actor);
1264
+ // - `skipping.epoch` is not the one adopted at, or the scene builds its
1265
+ // models the other way (`drops`);
1266
+ // - any model file a still actor places (or a file or art that model reads,
1267
+ // or the look switch, which is part of every model file's signature and
1268
+ // of nothing else a node is built from), or any art a still actor's Shape
1269
+ // names reads differently: one check a file and one an art, not one an
1270
+ // actor;
1271
+ // - (not the scene's own place: a frozen node asks, on every walk, whether
1272
+ // its parent's world matrix is the one it was frozen under, and computes
1273
+ // itself again when it is not: actornode.js.)
1274
+ // Between passes nothing here is asked: a frozen node thaws by itself the
1275
+ // moment any scene's still set changes (`skipping.clock`).
1276
+ // A settled pass that stops being alone part way (a live actor's node is
1277
+ // built, a callback syncs another scene) places every actor it has not yet
1278
+ // passed the way `syncActors` does, still ones included, in the same order.
1279
+ //
1280
+ // What is written down, and where:
1281
+ // - `world.stillKeeper`: its count, and its adoption, to which this world
1282
+ // adds the epoch adopted at, the version the Set was made at (for the
1283
+ // audit), how many still actors have a node, and what the shared things
1284
+ // read as: numbers and strings, and the art objects read, which the deck's
1285
+ // `sprites` table holds anyway. It refers to no actor, no node and no
1286
+ // runtime.
1287
+ // - `world.skipping.epoch`, `clock` and `clockAt`: two numbers and the
1288
+ // runtime's `stillClock` function (it reads a module's counter).
1289
+ // - on a still actor's node, `freezes` and `frozenAt`: numbers (actornode.js).
1290
+ //
1291
+ // A world that must never hold anything still (the scene editor's) sets
1292
+ // `world.staticActorsOff`; it, and a world with `instanceModels`, tells the
1293
+ // runtime so after its first pass (`releaseStill`), and from then on no actor
1294
+ // of the scene is still for anyone. A scene with a ground-height callback is
1295
+ // never alone, so this world never adopts and never freezes a node there; the
1296
+ // update loop and the physics system, which call nothing in the middle of
1297
+ // their work, still leave its still actors out.
1298
+ //
1299
+ // `world.auditStatic = n` (QA only; nothing sets it in play): each pass that
1300
+ // finds its runtime's still set as it was adopted (less what has been touched
1301
+ // since), and what its actors share as it was (a model file edited or the
1302
+ // look switched is no fault of an actor's), first
1303
+ // checks `n` of its actors, in turn, the way an ordinary pass would have, and one found changed is written
1304
+ // to `world.staticAuditFailures`, warned of once and touched (so that pass is
1305
+ // an ordinary one). The physics system does the same for every still body.
1306
+ // With `n` at least the number of still actors, every pass is a checked one.
1307
+
1308
+ // Every frozen node of the world is an ordinary ActorNode again from its next
1309
+ // walk: the epoch they froze at is not the epoch any more.
1310
+ function thaw(world) {
1311
+ world.skipping.epoch = (world.skipping.epoch ?? 0) + 1;
1312
+ }
1313
+
1314
+ // Something is about to run that the world's pass count does not see by
1315
+ // itself (`leavingTheEngine`, a frame without the key, a dispose): nothing
1316
+ // stays adopted, whatever pass is running will not adopt, and nothing stays
1317
+ // frozen.
1318
+ function dropStill(world) {
1319
+ world.stillKeeper.interrupt();
1320
+ thaw(world);
1321
+ }
1322
+
1323
+ // Keep the entire call-out counted, including every listener and re-entry.
1324
+ // Nested syncs cannot adopt while `running` includes this non-adopting pass.
1325
+ // Before a keeper exists, `unkept` counts the entry exactly as `syncActors`
1326
+ // does, so a keeper made by a listener sees the operation running around it.
1327
+ function outsideCall(world, fn) {
1328
+ const keeper = world.stillKeeper;
1329
+ if (!keeper) {
1330
+ world.unkept = (world.unkept ?? 0) + 1;
1331
+ try {
1332
+ return fn();
1333
+ } finally {
1334
+ world.unkept -= 1;
1335
+ if (world.stillKeeper) dropStill(world);
1336
+ }
1337
+ }
1338
+ const pass = keeper.begin(NOT_STILL);
1339
+ try {
1340
+ dropStill(world);
1341
+ return fn();
1342
+ } finally {
1343
+ keeper.end(pass, false);
1344
+ }
1345
+ }
1346
+
1347
+ // `syncActors` for a world with a keeper, or a scene that asks for one. The
1348
+ // invariant, which is about entry points and not about kinds of pass:
1349
+ //
1350
+ // From the moment a world has a keeper, the keeper sees EVERY entry into
1351
+ // and exit from `syncActors` on that world, of every kind (plain, skipping,
1352
+ // instanced, the editor's, settled, ordinary; any runtime). An adoption can
1353
+ // be recorded only by a pass that was alone from its entry to its exit, and
1354
+ // any pass of any kind that enters, or is running, drops it.
1355
+ //
1356
+ // `syncActors` is the one function through which the nodes of a world are
1357
+ // built, placed, parked, swapped and released (`swapSceneNodes`,
1358
+ // `ensureActorNode`, `buildNode`, `releaseUnseen`, the instanced draw are all
1359
+ // reached only from it); `disposeWorld`, the other, reports to the keeper and
1360
+ // leaves a world that never adopts again. So bracketing `syncActors` here is
1361
+ // bracketing every one of them.
1362
+ // - A pass that holds nothing still (its scene did not ask for
1363
+ // `staticActors`, or not with `skipUnchangedActors`, or the world is
1364
+ // disposed) is counted in, drops whatever was adopted before it does
1365
+ // anything, thaws (a skipping pass of a scene that does not ask would
1366
+ // otherwise place nodes that stay frozen), runs as it always did, and
1367
+ // never adopts on its way out.
1368
+ // - A pass of a scene that asks is `syncActorsHoldingStill`.
1369
+ // - A pass that entered BEFORE the world had a keeper was not seen entering.
1370
+ // `world.unkept` counts those while they run; a keeper is only ever made
1371
+ // from inside one (or with none running), and while the count is not zero
1372
+ // no pass is settled and none adopts.
1373
+ function syncActorsKept(world, runtime, sprites, dt, place = placeActor) {
1374
+ const keeper = (world.stillKeeper ??= runtime.newStillKeeper());
1375
+ if (runtime.keepsStaticActors === true && world.disposed !== true) {
1376
+ world.bakesLookLater = runtime.bakesLookLater === true;
1377
+ syncActorsHoldingStill(world, runtime, sprites, dt, runtime.dropsEmptyParts === true, place);
1378
+ return;
1379
+ }
1380
+ const pass = keeper.begin(NOT_STILL);
1381
+ thaw(world);
1382
+ try {
1383
+ syncActorsAsEver(world, runtime, sprites, dt, place);
1384
+ } finally {
1385
+ keeper.end(pass, false);
1386
+ }
1387
+ }
1388
+
1389
+ // The version a pass that holds nothing still begins with: no still set's.
1390
+ const NOT_STILL = -1;
1391
+
1392
+ // `syncActorsSkipping` for a scene that holds actors still: the same
1393
+ // statements, as one pass to the world's keeper (physics-2d
1394
+ // engine/stillClock.js has the rule). The keeper counts this entry before the
1395
+ // pass does anything; an ordinary pass thaws before its first actor; the pass
1396
+ // adopts only on its way out, and only if it was outermost, returned, was
1397
+ // alone to its end (no callout, by the generation), nobody entered meanwhile
1398
+ // (by the keeper's count), no pass the keeper never saw is running
1399
+ // (`world.unkept`), and the still set is the one it began with.
1400
+ function syncActorsHoldingStill(world, runtime, sprites, dt, drops, place) {
1401
+ const keeper = world.stillKeeper;
1402
+ if (world.syncDepth > 0) leavingTheEngine(world);
1403
+ const outermost = world.syncDepth === 0;
1404
+ const started = world.generation;
1405
+ world.skipping.on = true;
1406
+ world.syncDepth += 1;
1407
+ const audited = world.auditStatic > 0 ? adoptedForAudit(world) : null;
1408
+ const pass = keeper.begin(runtime.stillVersion);
1409
+ pass.audited = audited;
1410
+ // A pass the keeper never saw enter is running around this one.
1411
+ if (pass.settled && world.unkept > 0) keeper.demote(pass);
1412
+ if (!pass.settled) thaw(world);
1413
+ let finished = false;
1414
+ try {
1415
+ skippingPass(world, runtime, sprites, dt, outermost ? started : -1, drops, pass, place);
1416
+ finished = true;
1417
+ } finally {
1418
+ world.syncDepth -= 1;
1419
+ const alone = outermost && finished && world.generation === started;
1420
+ if (outermost && !alone) forgetSnapshots(world);
1421
+ endStillPass(world, runtime, pass, alone && !(world.unkept > 0), drops);
1422
+ }
1423
+ }
1424
+
1425
+ // The way out of `syncActorsHoldingStill`'s pass, whether it returned or threw.
1426
+ function endStillPass(world, runtime, pass, alone, drops) {
1427
+ const keeper = world.stillKeeper;
1428
+ // A world that holds nothing still says so to the runtime, so that the
1429
+ // update loop and the physics system hold nothing still either.
1430
+ if ((world.staticActorsOff === true || world.instanceModels === true) && runtime.stillActors?.size > 0) runtime.releaseStill();
1431
+ keeper.end(pass, alone, runtime.stillVersion, () => adoptStill(world, runtime, drops));
1432
+ if (keeper.adopted === null) thaw(world);
1433
+ }
1434
+
1435
+ // For the audit only (QA): what was adopted as a pass begins, if it was good
1436
+ // until then, and the epoch it was good at. Nothing is left out of a pass on
1437
+ // its word.
1438
+ function adoptedForAudit(world) {
1439
+ const keeper = world.stillKeeper;
1440
+ return keeper.adopted?.at === keeper.passes ? { ...keeper.adopted, epochNow: world.skipping.epoch } : null;
1441
+ }
1442
+
1443
+ // Whether a pass that began settled may stay so, asked after `beginPass` (a
1444
+ // scene change or a ground dressed anew has already been reported): nothing
1445
+ // has entered or been reported since it began, the adoption is of this epoch
1446
+ // and this way of building, and what the still actors share reads as it did.
1447
+ // The audit, if asked for, looks first, and what it finds touched makes the
1448
+ // pass ordinary. A pass that may not stay settled is ordinary from here:
1449
+ // nothing adopted, nothing frozen, before its first actor.
1450
+ function staysSettled(world, runtime, sprites, started, drops, pass) {
1451
+ if (pass.audited && isAuditable(world, runtime, sprites, started, drops, pass.audited)) auditStill(world, runtime, sprites, drops, pass.audited);
1452
+ if (pass.settled && isAsAdopted(world, runtime, sprites, started, drops, pass)) return true;
1453
+ if (pass.settled) world.stillKeeper.demote(pass);
1454
+ thaw(world);
1455
+ return false;
1456
+ }
1457
+
1458
+ // Whether the audit has anything to say this pass: what was adopted is of the
1459
+ // runtime's still set as made (some of it may have been touched since, by the
1460
+ // physics system's own audit earlier in the frame), and what its actors share
1461
+ // reads as it did (a model file edited is no fault of an actor's).
1462
+ function isAuditable(world, runtime, sprites, started, drops, was) {
1463
+ if (was.made !== runtime.stillActors?.made || world.generation !== started) return false;
1464
+ if (was.epoch !== was.epochNow || was.drops !== drops) return false;
1465
+ return sharedReadsTheSame(world, was, sprites, runtime.files);
1466
+ }
1467
+
1468
+ function isAsAdopted(world, runtime, sprites, started, drops, pass) {
1469
+ const keeper = world.stillKeeper;
1470
+ const still = keeper.adopted;
1471
+ if (!still || !keeper.alone(pass, runtime.stillVersion) || world.generation !== started || world.staticActorsOff === true) return false;
1472
+ if (still.epoch !== world.skipping.epoch || still.drops !== drops) return false;
1473
+ return sharedReadsTheSame(world, still, sprites, runtime.files);
1474
+ }
1475
+
1476
+ // Whether what the still actors share reads as it did when they were adopted:
1477
+ // each model file one of them places (its signature has the look switch in
1478
+ // it: `modelArtSignature`), each art one names.
1479
+ function sharedReadsTheSame(world, still, sprites, files) {
1480
+ if (!artReadsTheSame(still.arts, sprites)) return false;
1481
+ const placed = still.files;
1482
+ for (let i = 0; i < placed.length; i += 2) {
1483
+ if (modelSigOf(world, placed[i], sprites, files) !== placed[i + 1]) return false;
1484
+ }
1485
+ return true;
1486
+ }
1487
+
1488
+ // A settled pass: `skippingPass` for the actors that are not still.
1489
+ function settledPass(world, runtime, sprites, dt, started, drops, place) {
1490
+ const still = runtime.stillActors;
1491
+ const seen = new Set();
1492
+ let skipped = 0;
1493
+ for (const actor of runtime.getActors()) {
1494
+ const t = actor.components.Transform;
1495
+ if (!t) continue;
1496
+ if (world.generation === started && still.has(actor)) {
1497
+ skipped += 1;
1498
+ continue;
1499
+ }
1500
+ seen.add(actor.id);
1501
+ if (renderActorSleeps(world, actor)) continue;
1502
+ const entry = place(world, actor, t, sprites, runtime.files, started, drops);
1503
+ animateActor(world, entry, dt, actor);
1504
+ }
1505
+ if (world.generation !== started || seen.size + skipped !== world.nodes.size) {
1506
+ // A still actor passed over is still the runtime's, and keeps its node.
1507
+ for (const actor of still) seen.add(actor.id);
1508
+ releaseUnseen(world, seen);
1509
+ }
1510
+ if (world.instances.size > 0) {
1511
+ leavingTheEngine(world);
1512
+ aimInstances(world.camera);
1513
+ for (const instances of world.instances.values()) drawInstances(instances, world.camera);
1514
+ }
1515
+ return true;
1516
+ }
1517
+
1518
+ // Adopts the runtime's still set as this world's: every still actor's node
1519
+ // has just been found, placed and vouched for by an ordinary pass that nothing
1520
+ // interrupted. Each node may freeze from its next unchanged walk on. A still
1521
+ // actor whose model moves inside itself (a walker, a part in motion) cannot be
1522
+ // left alone: it is touched, and the pass after that adopts the rest.
1523
+ function adoptStill(world, runtime, drops) {
1524
+ const set = runtime.keepsStaticActors === true && world.staticActorsOff !== true ? runtime.stillActors : null;
1525
+ if (!set || set.size === 0) return null;
1526
+ const found = stillNodes(world, set, drops);
1527
+ // Not every one vouched for by this pass: nothing is adopted until one is.
1528
+ if (!found) return null;
1529
+ if (found.moving.length > 0) {
1530
+ for (const actor of found.moving) runtime.touch(actor);
1531
+ return null;
1532
+ }
1533
+ // From here a node may freeze, until the epoch moves or any scene's still
1534
+ // set changes.
1535
+ world.skipping.clock = runtime.stillClock;
1536
+ world.skipping.clockAt = world.skipping.clock();
1537
+ // (A node built by a pass that was not skipping, and kept since, is a plain
1538
+ // Group: it has nothing to freeze with, and three.js walks it as ever.)
1539
+ for (const node of found.nodes) {
1540
+ if (node instanceof ActorNode) {
1541
+ freezeWhenUnchanged(node);
1542
+ if (world.emptyNodes) freezeEmptyNode(world, node);
1543
+ if (world.emptyPass) checkEmptyPass(world);
1544
+ }
1545
+ }
1546
+ return { made: set.made, epoch: world.skipping.epoch, count: found.nodes.length, drops, files: [...found.files].flat(), arts: found.arts, cursor: 0 };
1547
+ }
1548
+
1549
+ // The nodes of the still actors, the ones whose model moves inside itself,
1550
+ // and what the rest share: each model file placed with its signature, each
1551
+ // art named with what it read as. Null when any of them has no node this
1552
+ // pass vouched for.
1553
+ function stillNodes(world, set, drops) {
1554
+ const found = { nodes: [], moving: [], files: new Map(), arts: [] };
1555
+ const artsSeen = new Set();
1556
+ for (const actor of set) {
1557
+ if (!actor.components.Transform) continue;
1558
+ const entry = world.nodes.get(actor.id);
1559
+ const built = entry && world.snapshots.get(entry)?.builtFrom;
1560
+ if (!built || built.drops !== drops) return null;
1561
+ if (movesInside(world, entry)) {
1562
+ found.moving.push(actor);
1563
+ continue;
1564
+ }
1565
+ found.nodes.push(entry.node);
1566
+ const file = actor.components.Model?.file;
1567
+ if (file) found.files.set(file, built.modelSig);
1568
+ addArtReads(found.arts, artsSeen, built.artReads);
1569
+ }
1570
+ return found;
1571
+ }
1572
+
1573
+ // Whether the node's model walks or has parts in motion.
1574
+ function movesInside(world, entry) {
1575
+ const template = entry.modelKey ? world.models.get(entry.modelKey)?.template : null;
1576
+ return Boolean(template) && !isStaticModel(template);
1577
+ }
1578
+
1579
+ // Adds to `arts` the reads of `artReads` (`[path, art, ready, ...]`) whose
1580
+ // path it does not have yet.
1581
+ function addArtReads(arts, seen, artReads) {
1582
+ for (let i = 0; i < artReads.length; i += 3) {
1583
+ if (seen.has(artReads[i])) continue;
1584
+ seen.add(artReads[i]);
1585
+ arts.push(artReads[i], artReads[i + 1], artReads[i + 2]);
1586
+ }
1587
+ }
1588
+
1589
+ // `world.auditStatic`: what an ordinary pass would have found for a few still
1590
+ // actors. See the notes above.
1591
+ function auditStill(world, runtime, sprites, drops, was) {
1592
+ const still = world.stillKeeper.adopted ?? was;
1593
+ const actors = [...runtime.stillActors];
1594
+ const many = Math.min(world.auditStatic, actors.length);
1595
+ for (let k = 0; k < many; k++) {
1596
+ const actor = actors[(still.cursor + k) % actors.length];
1597
+ const what = whatChanged(world, runtime, actor, sprites, drops);
1598
+ if (!what) continue;
1599
+ // Touched first: the note warns on the console, which is not the engine's.
1600
+ runtime.touch(actor);
1601
+ noteChangedStill(world, actor.id, what);
1602
+ }
1603
+ still.cursor = (still.cursor + many) % Math.max(1, actors.length);
1604
+ }
1605
+
1606
+ // What about a still actor no longer reads as the last ordinary pass left it,
1607
+ // or null.
1608
+ function whatChanged(world, runtime, actor, sprites, drops) {
1609
+ const t = actor.components.Transform;
1610
+ const entry = world.nodes.get(actor.id);
1611
+ if (!t) return entry ? 'its Transform (removed)' : null;
1612
+ if (!entry) return 'its node (gone)';
1613
+ if (!looksTheSame(world, entry, actor, sprites, runtime.files, drops)) return 'a component its node is built from';
1614
+ const node = entry.node;
1615
+ if (!sameTurn(node.position, t.x, t.y, t.z)) return 'its Transform (where it is)';
1616
+ if (actor.runtime?.quat || !turnedAs(node, t, world.snapshots.get(entry)?.turnedTo)) return 'its Transform (how it is turned)';
1617
+ if (node.computedFrom && !subtreeIsAsRecorded(node)) return 'its node, or an object under it,';
1618
+ return null;
1619
+ }
1620
+
1621
+ // Whether `turnNode` would leave the node's rotation as it is.
1622
+ function turnedAs(node, t, was) {
1623
+ if (!was || node.rotation.order !== was.order || !sameQuaternion(node.quaternion, was)) return false;
1624
+ return sameTurn(node.rotation, t.rotationX * DEG, t.rotationY * DEG, t.rotationZ * DEG);
1625
+ }