castle-web-cli 0.4.232 → 0.4.234

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (587) 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/api.d.ts +11 -0
  8. package/dist/api.js +43 -0
  9. package/dist/bundle.d.ts +64 -0
  10. package/dist/bundle.js +558 -2
  11. package/dist/castle-host/host.d.ts +18 -2
  12. package/dist/castle-host/host.js +844 -39
  13. package/dist/castleJson.d.ts +23 -2
  14. package/dist/castleJson.js +46 -2
  15. package/dist/check.d.ts +3 -1
  16. package/dist/check.js +20 -3
  17. package/dist/chunkLoader.d.ts +3 -0
  18. package/dist/chunkLoader.js +111 -0
  19. package/dist/devParty.d.ts +26 -0
  20. package/dist/devParty.js +231 -0
  21. package/dist/devSaveStorage.js +4 -0
  22. package/dist/devSessionStorage.js +50 -2
  23. package/dist/devSocial.d.ts +24 -0
  24. package/dist/devSocial.js +70 -0
  25. package/dist/ide.d.ts +2 -0
  26. package/dist/ide.js +119 -15
  27. package/dist/importPinMismatch.d.ts +22 -0
  28. package/dist/importPinMismatch.js +77 -0
  29. package/dist/importRegression.js +3 -15
  30. package/dist/imports.d.ts +10 -3
  31. package/dist/imports.js +88 -20
  32. package/dist/index.js +11 -4
  33. package/dist/init.js +1 -1
  34. package/dist/platformDoc.js +22 -0
  35. package/dist/routerFences.d.ts +5 -0
  36. package/dist/routerFences.js +12 -2
  37. package/dist/save-deck.d.ts +25 -1
  38. package/dist/save-deck.js +178 -9
  39. package/dist/serve.js +32 -11
  40. package/dist/shell/assets/{index-D2tWM896.js → index-DulbYIJm.js} +97 -97
  41. package/dist/shell/assets/index-MVLfNYd9.css +1 -0
  42. package/dist/shell/index.html +2 -2
  43. package/dist/taskSteer.d.ts +13 -0
  44. package/dist/taskSteer.js +22 -2
  45. package/dist/vitePlugins.d.ts +2 -1
  46. package/dist/vitePlugins.js +13 -0
  47. package/kits/base/castle.json +1 -1
  48. package/kits/base/package-lock.json +1 -1
  49. package/kits/base/sdk/README.md +339 -5
  50. package/kits/base/sdk/avatar.d.ts +6 -2
  51. package/kits/base/sdk/avatar.js +12 -4
  52. package/kits/base/sdk/castle.d.ts +7 -3
  53. package/kits/base/sdk/castle.js +2 -0
  54. package/kits/base/sdk/commands.d.ts +176 -1
  55. package/kits/base/sdk/commands.js +3 -0
  56. package/kits/base/sdk/display.d.ts +3 -0
  57. package/kits/base/sdk/display.js +9 -3
  58. package/kits/base/sdk/hub.d.ts +37 -6
  59. package/kits/base/sdk/hub.js +63 -4
  60. package/kits/base/sdk/multiplayer.d.ts +7 -1
  61. package/kits/base/sdk/multiplayer.js +148 -32
  62. package/kits/base/sdk/multiplayerProtocol.d.ts +2 -0
  63. package/kits/base/sdk/party.d.ts +23 -0
  64. package/kits/base/sdk/party.js +91 -0
  65. package/kits/base/sdk/reconnectBudget.d.ts +23 -0
  66. package/kits/base/sdk/reconnectBudget.js +96 -0
  67. package/kits/base/sdk/save.d.ts +38 -1
  68. package/kits/base/sdk/save.js +81 -7
  69. package/kits/base/sdk/server/hub.d.ts +117 -0
  70. package/kits/base/sdk/server/hub.js +119 -2
  71. package/kits/base/sdk/server/platformHandle.d.ts +43 -1
  72. package/kits/base/sdk/server/storage.d.ts +17 -0
  73. package/kits/base/sdk/server/storage.js +65 -3
  74. package/kits/base/sdk/server/wrapper.d.ts +43 -6
  75. package/kits/base/sdk/server/wrapper.js +93 -9
  76. package/kits/base/sdk/social.d.ts +9 -0
  77. package/kits/base/sdk/social.js +5 -0
  78. package/kits/hub-game/CLAUDE.md +451 -13
  79. package/kits/hub-game/README.md +63 -0
  80. package/kits/hub-game/blueprints/avatar-10.scene +28 -0
  81. package/kits/hub-game/blueprints/avatar-11.scene +28 -0
  82. package/kits/hub-game/blueprints/avatar-12.scene +28 -0
  83. package/kits/hub-game/blueprints/avatar-13.scene +28 -0
  84. package/kits/hub-game/blueprints/avatar-14.scene +28 -0
  85. package/kits/hub-game/blueprints/avatar-15.scene +28 -0
  86. package/kits/hub-game/blueprints/avatar-4.scene +28 -0
  87. package/kits/hub-game/blueprints/avatar-5.scene +28 -0
  88. package/kits/hub-game/blueprints/avatar-6.scene +28 -0
  89. package/kits/hub-game/blueprints/avatar-7.scene +28 -0
  90. package/kits/hub-game/blueprints/avatar-8.scene +28 -0
  91. package/kits/hub-game/blueprints/avatar-9.scene +28 -0
  92. package/kits/hub-game/castle.json +5 -5
  93. package/kits/hub-game/code/client/act.js +312 -0
  94. package/kits/hub-game/code/client/actionLayout.js +147 -0
  95. package/kits/hub-game/code/client/actionOverflow.js +556 -0
  96. package/kits/hub-game/code/client/actorBudget.js +47 -0
  97. package/kits/hub-game/code/client/arrivalCamera.js +50 -0
  98. package/kits/hub-game/code/client/askSlot.js +117 -0
  99. package/kits/hub-game/code/client/attention.js +11 -2
  100. package/kits/hub-game/code/client/avatar.js +311 -35
  101. package/kits/hub-game/code/client/avatarCap.js +228 -0
  102. package/kits/hub-game/code/client/avatarColors.js +70 -0
  103. package/kits/hub-game/code/client/avatarFaces.js +21 -0
  104. package/kits/hub-game/code/client/avatarShare.js +253 -0
  105. package/kits/hub-game/code/client/backVisibility.js +13 -0
  106. package/kits/hub-game/code/client/ballot.js +472 -0
  107. package/kits/hub-game/code/client/build.js +38 -0
  108. package/kits/hub-game/code/client/chat.js +41 -5
  109. package/kits/hub-game/code/client/chatModeration.js +5 -0
  110. package/kits/hub-game/code/client/chrome.js +2144 -160
  111. package/kits/hub-game/code/client/companion.js +716 -0
  112. package/kits/hub-game/code/client/companionDress.js +99 -0
  113. package/kits/hub-game/code/client/crowdNames.js +241 -0
  114. package/kits/hub-game/code/client/decor.js +515 -0
  115. package/kits/hub-game/code/client/defaultEnvironment.js +194 -0
  116. package/kits/hub-game/code/client/doorErrors.js +39 -0
  117. package/kits/hub-game/code/client/earned.js +131 -0
  118. package/kits/hub-game/code/client/emoteBubble.js +75 -0
  119. package/kits/hub-game/code/client/fall.js +18 -0
  120. package/kits/hub-game/code/client/farAvatars.js +233 -0
  121. package/kits/hub-game/code/client/firstJoin.js +9 -2
  122. package/kits/hub-game/code/client/fpsTelemetry.js +50 -0
  123. package/kits/hub-game/code/client/frameBatch.js +5 -0
  124. package/kits/hub-game/code/client/grab.js +368 -29
  125. package/kits/hub-game/code/client/hookLayer.js +385 -20
  126. package/kits/hub-game/code/client/hudCopy.js +51 -0
  127. package/kits/hub-game/code/client/hudRate.js +20 -0
  128. package/kits/hub-game/code/client/idle.js +177 -24
  129. package/kits/hub-game/code/client/interestCap.js +81 -0
  130. package/kits/hub-game/code/client/invites.js +231 -0
  131. package/kits/hub-game/code/client/joinError.js +9 -0
  132. package/kits/hub-game/code/client/keys.js +36 -0
  133. package/kits/hub-game/code/client/labelsNear.js +234 -0
  134. package/kits/hub-game/code/client/landscapeLayout.js +17 -0
  135. package/kits/hub-game/code/client/layoutCache.js +264 -0
  136. package/kits/hub-game/code/client/loadTelemetry.js +20 -0
  137. package/kits/hub-game/code/client/loadingCover.js +148 -0
  138. package/kits/hub-game/code/client/loadingEntry.js +8 -0
  139. package/kits/hub-game/code/client/menuIcons.js +34 -0
  140. package/kits/hub-game/code/client/menuRows.js +43 -0
  141. package/kits/hub-game/code/client/modelReady.js +7 -0
  142. package/kits/hub-game/code/client/pack.js +6 -2
  143. package/kits/hub-game/code/client/packFormat.js +3 -3
  144. package/kits/hub-game/code/client/padCueArrival.js +23 -0
  145. package/kits/hub-game/code/client/padCues.js +112 -0
  146. package/kits/hub-game/code/client/padOccupancy.js +88 -0
  147. package/kits/hub-game/code/client/padReadability.js +26 -0
  148. package/kits/hub-game/code/client/padRings.js +69 -0
  149. package/kits/hub-game/code/client/pushVisit.js +14 -0
  150. package/kits/hub-game/code/client/quality.js +205 -0
  151. package/kits/hub-game/code/client/qualityEntry.js +55 -0
  152. package/kits/hub-game/code/client/rehello.js +167 -0
  153. package/kits/hub-game/code/client/safeLayout.js +338 -0
  154. package/kits/hub-game/code/client/safeStyle.js +42 -0
  155. package/kits/hub-game/code/client/say.js +12 -3
  156. package/kits/hub-game/code/client/shot.js +146 -0
  157. package/kits/hub-game/code/client/shotFit.js +56 -0
  158. package/kits/hub-game/code/client/signIn.js +28 -0
  159. package/kits/hub-game/code/client/sound.js +63 -8
  160. package/kits/hub-game/code/client/soundscape.js +1151 -0
  161. package/kits/hub-game/code/client/soundscapeActions.js +99 -0
  162. package/kits/hub-game/code/client/soundscapeAmbience.js +453 -0
  163. package/kits/hub-game/code/client/soundscapeBaked.js +143 -0
  164. package/kits/hub-game/code/client/soundscapeBusker.js +217 -0
  165. package/kits/hub-game/code/client/soundscapeCourt.js +200 -0
  166. package/kits/hub-game/code/client/soundscapeCrowd.js +331 -0
  167. package/kits/hub-game/code/client/soundscapeCues.js +362 -0
  168. package/kits/hub-game/code/client/soundscapeMap.js +181 -0
  169. package/kits/hub-game/code/client/soundscapeMarket.js +176 -0
  170. package/kits/hub-game/code/client/soundscapeMusic.js +126 -0
  171. package/kits/hub-game/code/client/soundscapeMusicEngine.js +460 -0
  172. package/kits/hub-game/code/client/soundscapeSimlish.js +737 -0
  173. package/kits/hub-game/code/client/soundscapeSongs.js +127 -0
  174. package/kits/hub-game/code/client/soundscapeSongsRound3.js +63 -0
  175. package/kits/hub-game/code/client/soundscapeSynthesis.js +168 -0
  176. package/kits/hub-game/code/client/soundscapeUi.js +211 -0
  177. package/kits/hub-game/code/client/soundscapeVoice.js +1209 -0
  178. package/kits/hub-game/code/client/soundscapeWaves.js +206 -0
  179. package/kits/hub-game/code/client/spin.js +101 -0
  180. package/kits/hub-game/code/client/state.js +162 -1
  181. package/kits/hub-game/code/client/stuck.js +259 -0
  182. package/kits/hub-game/code/client/talk.js +714 -59
  183. package/kits/hub-game/code/client/tiers.js +543 -52
  184. package/kits/hub-game/code/client/toastBand.js +37 -0
  185. package/kits/hub-game/code/client/together.js +39 -2
  186. package/kits/hub-game/code/client/visibility.js +43 -0
  187. package/kits/hub-game/code/client/weakestLookBake.js +92 -0
  188. package/kits/hub-game/code/client/weakestTier.js +295 -0
  189. package/kits/hub-game/code/client/wear.js +461 -170
  190. package/kits/hub-game/code/client/worldLabels.js +241 -0
  191. package/kits/hub-game/code/client/yours.js +200 -0
  192. package/kits/hub-game/code/companionSpec.js +45 -0
  193. package/kits/hub-game/code/npcDisplayText.js +55 -0
  194. package/kits/hub-game/code/privateText.js +7 -0
  195. package/kits/hub-game/code/server/act.js +124 -0
  196. package/kits/hub-game/code/server/actions.js +138 -0
  197. package/kits/hub-game/code/server/actors.js +11 -2
  198. package/kits/hub-game/code/server/analytics.js +83 -0
  199. package/kits/hub-game/code/server/anonymousEntry.js +49 -0
  200. package/kits/hub-game/code/server/arrivalPose.js +36 -0
  201. package/kits/hub-game/code/server/ask.js +155 -0
  202. package/kits/hub-game/code/server/ballot.js +539 -0
  203. package/kits/hub-game/code/server/cells.js +100 -0
  204. package/kits/hub-game/code/server/companion.js +107 -0
  205. package/kits/hub-game/code/server/cues.js +70 -0
  206. package/kits/hub-game/code/server/decor.js +269 -0
  207. package/kits/hub-game/code/server/doorAnalytics.js +52 -0
  208. package/kits/hub-game/code/server/earned.js +478 -0
  209. package/kits/hub-game/code/server/frameBatch.js +183 -0
  210. package/kits/hub-game/code/server/friendBests.js +166 -0
  211. package/kits/hub-game/code/server/friendsAmong.js +272 -0
  212. package/kits/hub-game/code/server/history.js +7 -0
  213. package/kits/hub-game/code/server/hub.js +2510 -95
  214. package/kits/hub-game/code/server/idle.js +60 -12
  215. package/kits/hub-game/code/server/index.js +28 -6
  216. package/kits/hub-game/code/server/invites.js +19 -0
  217. package/kits/hub-game/code/server/labels.js +36 -2
  218. package/kits/hub-game/code/server/loadAbandon.js +106 -0
  219. package/kits/hub-game/code/server/manifest.js +586 -7
  220. package/kits/hub-game/code/server/menu.js +161 -0
  221. package/kits/hub-game/code/server/npcs.js +1025 -113
  222. package/kits/hub-game/code/server/observe.js +408 -0
  223. package/kits/hub-game/code/server/padOccupancy.js +85 -0
  224. package/kits/hub-game/code/server/party.js +2 -2
  225. package/kits/hub-game/code/server/players.js +30 -0
  226. package/kits/hub-game/code/server/resumePose.js +152 -0
  227. package/kits/hub-game/code/server/say.js +1 -1
  228. package/kits/hub-game/code/server/shot.js +110 -0
  229. package/kits/hub-game/code/server/standing.js +123 -0
  230. package/kits/hub-game/code/server/storageLimit.js +187 -0
  231. package/kits/hub-game/code/server/vis.js +175 -0
  232. package/kits/hub-game/code/server/wear.js +12 -0
  233. package/kits/hub-game/code/server/yours.js +59 -0
  234. package/kits/hub-game/code/shared/act.js +35 -0
  235. package/kits/hub-game/code/shared/cues.js +9 -0
  236. package/kits/hub-game/code/shared/danceIdle.js +28 -0
  237. package/kits/hub-game/code/shared/decor.js +41 -0
  238. package/kits/hub-game/code/shared/loadStages.js +12 -0
  239. package/kits/hub-game/code/shared/quality.js +74 -0
  240. package/kits/hub-game/code/shared/say.js +2 -0
  241. package/kits/hub-game/code/shared/shot.js +53 -0
  242. package/kits/hub-game/code/shared/spin.js +57 -0
  243. package/kits/hub-game/code/systems/hub.js +1753 -202
  244. package/kits/hub-game/docs/analytics.md +279 -0
  245. package/kits/hub-game/docs/content-pack.md +1 -1
  246. package/kits/hub-game/docs/contract.md +3475 -77
  247. package/kits/hub-game/docs/home-pieces.md +71 -0
  248. package/kits/hub-game/docs/observed-progress.md +252 -0
  249. package/kits/hub-game/main.jsx +2 -0
  250. package/kits/hub-game/models/avatar-10.pxmodel +28 -0
  251. package/kits/hub-game/models/avatar-11.pxmodel +28 -0
  252. package/kits/hub-game/models/avatar-12.pxmodel +27 -0
  253. package/kits/hub-game/models/avatar-13.pxmodel +24 -0
  254. package/kits/hub-game/models/avatar-14.pxmodel +29 -0
  255. package/kits/hub-game/models/avatar-15.pxmodel +24 -0
  256. package/kits/hub-game/models/avatar-4.pxmodel +29 -0
  257. package/kits/hub-game/models/avatar-5.pxmodel +27 -0
  258. package/kits/hub-game/models/avatar-6.pxmodel +26 -0
  259. package/kits/hub-game/models/avatar-7.pxmodel +25 -0
  260. package/kits/hub-game/models/avatar-8.pxmodel +24 -0
  261. package/kits/hub-game/models/avatar-9.pxmodel +30 -0
  262. package/kits/hub-game/models/earned/badge-round.pxmodel +100 -0
  263. package/kits/hub-game/models/earned/badge-shield.pxmodel +117 -0
  264. package/kits/hub-game/models/earned/badge-star.pxmodel +87 -0
  265. package/kits/hub-game/models/earned/belt-plain.pxmodel +72 -0
  266. package/kits/hub-game/models/earned/held-ball.pxmodel +43 -0
  267. package/kits/hub-game/models/earned/held-lantern.pxmodel +85 -0
  268. package/kits/hub-game/models/earned/held-net.pxmodel +57 -0
  269. package/kits/hub-game/models/earned/held-trophy.pxmodel +109 -0
  270. package/kits/hub-game/models/earned/pin-round.pxmodel +62 -0
  271. package/kits/hub-game/models/earned/sash-plain.pxmodel +66 -0
  272. package/kits/hub-game/models/earned/square/belt-plain.pxmodel +104 -0
  273. package/kits/hub-game/models/earned/square/sash-plain.pxmodel +98 -0
  274. package/kits/hub-game/models/hats/bat-clip.pxmodel +206 -0
  275. package/kits/hub-game/models/hats/beekeeper.pxmodel +149 -0
  276. package/kits/hub-game/models/hats/cap.pxmodel +162 -0
  277. package/kits/hub-game/models/hats/captain.pxmodel +178 -0
  278. package/kits/hub-game/models/hats/crooked-top.pxmodel +172 -0
  279. package/kits/hub-game/models/hats/flower-crown.pxmodel +451 -0
  280. package/kits/hub-game/models/hats/foam-crown.pxmodel +179 -0
  281. package/kits/hub-game/models/hats/lantern.pxmodel +230 -0
  282. package/kits/hub-game/models/hats/laurel.pxmodel +533 -0
  283. package/kits/hub-game/models/hats/lighthouse.pxmodel +96 -0
  284. package/kits/hub-game/models/hats/sailor.pxmodel +141 -0
  285. package/kits/hub-game/models/hats/souwester.pxmodel +131 -0
  286. package/kits/hub-game/models/hats/straw.pxmodel +139 -0
  287. package/kits/hub-game/models/hats/sunflower.pxmodel +406 -0
  288. package/kits/hub-game/models/hats/sweatband.pxmodel +112 -0
  289. package/kits/hub-game/models/hats/witch.pxmodel +147 -0
  290. package/kits/hub-game/package-lock.json +10 -1
  291. package/kits/hub-game/package.json +6 -2
  292. package/kits/hub-game/play/player.js +142 -0
  293. package/kits/hub-game/play/registry.js +47 -0
  294. package/kits/hub-game/play.jsx +37 -0
  295. package/kits/hub-game/scripts/check.mjs +117 -16
  296. package/kits/hub-game/scripts/companion-follower-wire.json +1 -0
  297. package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +132 -0
  298. package/kits/hub-game/scripts/fixtures/decor-keyless.json +293 -0
  299. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +26 -0
  300. package/kits/hub-game/scripts/fixtures/fake-dom.mjs +123 -0
  301. package/kits/hub-game/scripts/fixtures/interest-legacy.json +385 -0
  302. package/kits/hub-game/scripts/fixtures/npc-notes-v1.77.jsonl +4 -0
  303. package/kits/hub-game/scripts/fixtures/vis-shared-wire.json +1 -0
  304. package/kits/hub-game/scripts/gen-avatars.mjs +933 -16
  305. package/kits/hub-game/scripts/gen-earned.mjs +285 -0
  306. package/kits/hub-game/scripts/gen-hats.mjs +827 -0
  307. package/kits/hub-game/scripts/grab.before-orbit.mjs +400 -0
  308. package/kits/hub-game/scripts/pose-storage-fixture.mjs +46 -0
  309. package/kits/hub-game/scripts/soundscape-wave-analysis.mjs +125 -0
  310. package/kits/hub-game/scripts/test-act-client.mjs +186 -0
  311. package/kits/hub-game/scripts/test-act.mjs +171 -0
  312. package/kits/hub-game/scripts/test-action-layout.mjs +80 -0
  313. package/kits/hub-game/scripts/test-action-observers.mjs +46 -0
  314. package/kits/hub-game/scripts/test-actions-client.mjs +853 -0
  315. package/kits/hub-game/scripts/test-actions.mjs +298 -0
  316. package/kits/hub-game/scripts/test-actor-budget.mjs +44 -0
  317. package/kits/hub-game/scripts/test-actors.mjs +38 -23
  318. package/kits/hub-game/scripts/test-analytics.mjs +76 -0
  319. package/kits/hub-game/scripts/test-anonymous-entry.mjs +28 -0
  320. package/kits/hub-game/scripts/test-arrival-pose-server.mjs +196 -0
  321. package/kits/hub-game/scripts/test-arrival-pose.mjs +24 -0
  322. package/kits/hub-game/scripts/test-ask-client.mjs +358 -0
  323. package/kits/hub-game/scripts/test-ask-slot.mjs +85 -0
  324. package/kits/hub-game/scripts/test-ask.mjs +269 -0
  325. package/kits/hub-game/scripts/test-attention.mjs +10 -1
  326. package/kits/hub-game/scripts/test-avatar-cap.mjs +379 -0
  327. package/kits/hub-game/scripts/test-avatar-colors.mjs +72 -0
  328. package/kits/hub-game/scripts/test-avatar-models.mjs +181 -0
  329. package/kits/hub-game/scripts/test-avatar-share.mjs +318 -0
  330. package/kits/hub-game/scripts/test-avatar-wire.mjs +792 -0
  331. package/kits/hub-game/scripts/test-avatar.mjs +584 -7
  332. package/kits/hub-game/scripts/test-back-visibility.mjs +82 -0
  333. package/kits/hub-game/scripts/test-ballot.mjs +1008 -0
  334. package/kits/hub-game/scripts/test-ban-join.mjs +121 -13
  335. package/kits/hub-game/scripts/test-build.mjs +49 -0
  336. package/kits/hub-game/scripts/test-cells.mjs +71 -0
  337. package/kits/hub-game/scripts/test-chat.mjs +863 -0
  338. package/kits/hub-game/scripts/test-classic.mjs +2 -0
  339. package/kits/hub-game/scripts/test-companion-chat.mjs +216 -0
  340. package/kits/hub-game/scripts/test-companion-client.mjs +1167 -0
  341. package/kits/hub-game/scripts/test-companion.mjs +259 -0
  342. package/kits/hub-game/scripts/test-control-layout-dom.mjs +120 -0
  343. package/kits/hub-game/scripts/test-crowd-names.mjs +205 -0
  344. package/kits/hub-game/scripts/test-decor-client.mjs +344 -0
  345. package/kits/hub-game/scripts/test-decor.mjs +464 -0
  346. package/kits/hub-game/scripts/test-default-environment-root.mjs +95 -0
  347. package/kits/hub-game/scripts/test-default-environment.mjs +267 -0
  348. package/kits/hub-game/scripts/test-door-analytics.mjs +58 -0
  349. package/kits/hub-game/scripts/test-door-jump.mjs +100 -0
  350. package/kits/hub-game/scripts/test-earned-client.mjs +459 -0
  351. package/kits/hub-game/scripts/test-earned.mjs +1224 -0
  352. package/kits/hub-game/scripts/test-emote-bubble.mjs +110 -0
  353. package/kits/hub-game/scripts/test-far-avatars.mjs +340 -0
  354. package/kits/hub-game/scripts/test-fps-telemetry.mjs +112 -0
  355. package/kits/hub-game/scripts/test-frame-batch.mjs +252 -0
  356. package/kits/hub-game/scripts/test-fresh-friends.mjs +118 -0
  357. package/kits/hub-game/scripts/test-friend-bests.mjs +435 -0
  358. package/kits/hub-game/scripts/test-grab-orbit.mjs +961 -0
  359. package/kits/hub-game/scripts/test-grab.mjs +7 -0
  360. package/kits/hub-game/scripts/test-hats.mjs +422 -168
  361. package/kits/hub-game/scripts/test-high-only.mjs +170 -0
  362. package/kits/hub-game/scripts/test-hub-leaving.mjs +203 -0
  363. package/kits/hub-game/scripts/test-hub-ops.mjs +758 -2
  364. package/kits/hub-game/scripts/test-hub-trip.mjs +1594 -12
  365. package/kits/hub-game/scripts/test-hud-clear.mjs +484 -57
  366. package/kits/hub-game/scripts/test-hud-defects-dom.mjs +100 -0
  367. package/kits/hub-game/scripts/test-hud-rate.mjs +224 -0
  368. package/kits/hub-game/scripts/test-hud-safe-visibility-dom.mjs +83 -0
  369. package/kits/hub-game/scripts/test-idle.mjs +427 -1
  370. package/kits/hub-game/scripts/test-interest-cap.mjs +36 -0
  371. package/kits/hub-game/scripts/test-interest-cells.mjs +513 -0
  372. package/kits/hub-game/scripts/test-interest-client.mjs +118 -0
  373. package/kits/hub-game/scripts/test-interest.mjs +15 -0
  374. package/kits/hub-game/scripts/test-invites-client.mjs +430 -0
  375. package/kits/hub-game/scripts/test-invites.mjs +109 -0
  376. package/kits/hub-game/scripts/test-keys.mjs +46 -1
  377. package/kits/hub-game/scripts/test-labels.mjs +664 -0
  378. package/kits/hub-game/scripts/test-landscape-layout.mjs +194 -0
  379. package/kits/hub-game/scripts/test-list-scroll-dom.mjs +49 -0
  380. package/kits/hub-game/scripts/test-load-abandon.mjs +246 -0
  381. package/kits/hub-game/scripts/test-loading-cover.mjs +162 -0
  382. package/kits/hub-game/scripts/test-manifest.mjs +472 -0
  383. package/kits/hub-game/scripts/test-menu-client.mjs +585 -0
  384. package/kits/hub-game/scripts/test-menu.mjs +319 -0
  385. package/kits/hub-game/scripts/test-npcs.mjs +2528 -13
  386. package/kits/hub-game/scripts/test-object-entry.mjs +76 -0
  387. package/kits/hub-game/scripts/test-observed.mjs +745 -0
  388. package/kits/hub-game/scripts/test-pack.mjs +7 -0
  389. package/kits/hub-game/scripts/test-pad-cues.mjs +304 -0
  390. package/kits/hub-game/scripts/test-pad-occupancy.mjs +177 -0
  391. package/kits/hub-game/scripts/test-picker.mjs +541 -0
  392. package/kits/hub-game/scripts/test-placement-cache.mjs +690 -0
  393. package/kits/hub-game/scripts/test-progress-reset.mjs +559 -0
  394. package/kits/hub-game/scripts/test-push-visit.mjs +26 -0
  395. package/kits/hub-game/scripts/test-quality.mjs +385 -0
  396. package/kits/hub-game/scripts/test-rehello.mjs +1733 -0
  397. package/kits/hub-game/scripts/test-relations-among.mjs +222 -0
  398. package/kits/hub-game/scripts/test-relations-refresh.mjs +188 -0
  399. package/kits/hub-game/scripts/test-resume-action-order.mjs +598 -0
  400. package/kits/hub-game/scripts/test-resume-held.mjs +239 -0
  401. package/kits/hub-game/scripts/test-resume-pose.mjs +142 -0
  402. package/kits/hub-game/scripts/test-safe-events-dom.mjs +116 -0
  403. package/kits/hub-game/scripts/test-safe-layout.mjs +330 -0
  404. package/kits/hub-game/scripts/test-say.mjs +1 -1
  405. package/kits/hub-game/scripts/test-shot.mjs +901 -0
  406. package/kits/hub-game/scripts/test-signin-client.mjs +45 -0
  407. package/kits/hub-game/scripts/test-soundscape.mjs +5437 -0
  408. package/kits/hub-game/scripts/test-spin.mjs +314 -0
  409. package/kits/hub-game/scripts/test-standing.mjs +449 -0
  410. package/kits/hub-game/scripts/test-storage-limit.mjs +333 -0
  411. package/kits/hub-game/scripts/test-stuck.mjs +1904 -0
  412. package/kits/hub-game/scripts/test-talk-overlay-dom.mjs +130 -0
  413. package/kits/hub-game/scripts/test-tier-cells.mjs +706 -0
  414. package/kits/hub-game/scripts/test-tiers-render.mjs +412 -0
  415. package/kits/hub-game/scripts/test-tiers.mjs +476 -2
  416. package/kits/hub-game/scripts/test-toast-band.mjs +61 -0
  417. package/kits/hub-game/scripts/test-try-on.mjs +22 -22
  418. package/kits/hub-game/scripts/test-vis.mjs +770 -0
  419. package/kits/hub-game/scripts/test-visibility.mjs +134 -0
  420. package/kits/hub-game/scripts/test-weakest-tier.mjs +924 -0
  421. package/kits/hub-game/scripts/test-world-labels.mjs +367 -0
  422. package/kits/hub-game/scripts/test-yours-chrome.mjs +210 -0
  423. package/kits/hub-game/scripts/test-yours.mjs +403 -0
  424. package/kits/multiplayer-3d/CLAUDE.md +50 -0
  425. package/kits/multiplayer-3d/castle.json +5 -5
  426. package/kits/multiplayer-3d/code/client/avatars.js +7 -0
  427. package/kits/multiplayer-3d/code/client/gait.js +65 -0
  428. package/kits/multiplayer-3d/code/client/joinFailure.js +27 -0
  429. package/kits/multiplayer-3d/code/client/nameTags.js +59 -4
  430. package/kits/multiplayer-3d/code/client/resumeGate.js +139 -0
  431. package/kits/multiplayer-3d/code/options.js +5 -0
  432. package/kits/multiplayer-3d/code/server/ownership.js +10 -2
  433. package/kits/multiplayer-3d/code/server/sceneBodies.js +12 -0
  434. package/kits/multiplayer-3d/code/server/world.js +7 -0
  435. package/kits/multiplayer-3d/code/systems/multiplayer.js +443 -34
  436. package/kits/multiplayer-3d/package-lock.json +8 -1
  437. package/kits/multiplayer-3d/package.json +3 -1
  438. package/kits/multiplayer-3d/scripts/fixtures/README.md +11 -0
  439. package/kits/multiplayer-3d/scripts/fixtures/ownership-legacy.json +2 -0
  440. package/kits/multiplayer-3d/scripts/ownership-harness.mjs +102 -0
  441. package/kits/multiplayer-3d/scripts/ownership-loader.mjs +46 -0
  442. package/kits/multiplayer-3d/scripts/ownership-worker.mjs +15 -0
  443. package/kits/multiplayer-3d/scripts/record-ownership-session.mjs +98 -0
  444. package/kits/multiplayer-3d/scripts/test-eligible-claims.mjs +167 -0
  445. package/kits/multiplayer-3d/scripts/test-join-watchdog.mjs +436 -0
  446. package/kits/multiplayer-3d/scripts/test-own-name-tag.mjs +247 -0
  447. package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +624 -0
  448. package/kits/physics-2d/CLAUDE.md +19 -1
  449. package/kits/physics-2d/castle.json +2 -2
  450. package/kits/physics-2d/engine/frozenActors.js +233 -0
  451. package/kits/physics-2d/engine/scene.js +337 -3
  452. package/kits/physics-2d/engine/skyKey.js +129 -0
  453. package/kits/physics-2d/engine/stillClock.js +106 -0
  454. package/kits/physics-2d/engine/updateBudget.js +21 -0
  455. package/kits/physics-2d/eslint.config.js +1 -1
  456. package/kits/physics-2d/play/behaviors/AnalogStick.js +198 -0
  457. package/kits/physics-2d/play/behaviors/Camera.js +40 -0
  458. package/kits/physics-2d/play/behaviors/Collider.js +122 -0
  459. package/kits/physics-2d/play/behaviors/Draggable.js +115 -0
  460. package/kits/physics-2d/play/behaviors/Goal.js +46 -0
  461. package/kits/physics-2d/play/behaviors/Joints.js +126 -0
  462. package/kits/physics-2d/play/behaviors/Layout.js +71 -0
  463. package/kits/physics-2d/play/behaviors/RigidBody.js +57 -0
  464. package/kits/physics-2d/play/behaviors/Slingshot.js +142 -0
  465. package/kits/physics-2d/play/behaviors/SoundPlayer.js +263 -0
  466. package/kits/physics-2d/play/behaviors/Sprite.js +406 -0
  467. package/kits/physics-2d/play/behaviors/Style.js +209 -0
  468. package/kits/physics-2d/play/behaviors/Text.js +85 -0
  469. package/kits/physics-2d/play/behaviors/Video.js +93 -0
  470. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +326 -1
  471. package/kits/physics-3d/CLAUDE.md +42 -529
  472. package/kits/physics-3d/behaviors/Body.jsx +3 -0
  473. package/kits/physics-3d/behaviors/Model.jsx +3 -0
  474. package/kits/physics-3d/behaviors/Player.jsx +661 -87
  475. package/kits/physics-3d/behaviors/Shape.jsx +3 -0
  476. package/kits/physics-3d/behaviors/Solid.jsx +3 -0
  477. package/kits/physics-3d/behaviors/Transform.jsx +3 -0
  478. package/kits/physics-3d/castle.json +3 -3
  479. package/kits/physics-3d/docs/engine-camera.md +542 -0
  480. package/kits/physics-3d/docs/engine-frame-cap.md +136 -0
  481. package/kits/physics-3d/docs/engine-load.md +149 -0
  482. package/kits/physics-3d/docs/engine-look.md +114 -0
  483. package/kits/physics-3d/docs/engine-shadows.md +372 -0
  484. package/kits/physics-3d/docs/engine-skip-work.md +187 -0
  485. package/kits/physics-3d/docs/engine-sky.md +198 -0
  486. package/kits/physics-3d/docs/engine-static-actors.md +226 -0
  487. package/kits/physics-3d/docs/engine-view.md +37 -0
  488. package/kits/physics-3d/docs/pxmodel-format.md +9 -1
  489. package/kits/physics-3d/engine3d/PlayOnly3D.jsx +5 -1
  490. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +19 -277
  491. package/kits/physics-3d/engine3d/actornode.js +87 -0
  492. package/kits/physics-3d/engine3d/animationBudget.js +23 -0
  493. package/kits/physics-3d/engine3d/branches.js +3 -13
  494. package/kits/physics-3d/engine3d/cage.js +2 -7
  495. package/kits/physics-3d/engine3d/cageops.js +2 -17
  496. package/kits/physics-3d/engine3d/dataBehaviors.js +12 -0
  497. package/kits/physics-3d/engine3d/editorWorld.js +6 -0
  498. package/kits/physics-3d/engine3d/emptynodes.js +232 -0
  499. package/kits/physics-3d/engine3d/framecap.js +99 -0
  500. package/kits/physics-3d/engine3d/frozenphysics.js +140 -0
  501. package/kits/physics-3d/engine3d/frozenstatics.js +273 -0
  502. package/kits/physics-3d/engine3d/gait.js +126 -0
  503. package/kits/physics-3d/engine3d/initialModelFiles.js +18 -0
  504. package/kits/physics-3d/engine3d/kithooks.js +47 -0
  505. package/kits/physics-3d/engine3d/look.js +514 -48
  506. package/kits/physics-3d/engine3d/lookbake.js +208 -0
  507. package/kits/physics-3d/engine3d/materialpresets.js +2 -0
  508. package/kits/physics-3d/engine3d/modelFiles.js +3 -17
  509. package/kits/physics-3d/engine3d/modelMath.js +49 -0
  510. package/kits/physics-3d/engine3d/modelready.js +16 -0
  511. package/kits/physics-3d/engine3d/motion.js +39 -10
  512. package/kits/physics-3d/engine3d/nearshadows.js +106 -21
  513. package/kits/physics-3d/engine3d/optimize.js +9 -5
  514. package/kits/physics-3d/engine3d/orbitinput.js +522 -10
  515. package/kits/physics-3d/engine3d/orbitlens.js +48 -0
  516. package/kits/physics-3d/engine3d/ownmodel.js +213 -0
  517. package/kits/physics-3d/engine3d/partgeometry.js +1 -16
  518. package/kits/physics-3d/engine3d/paths.js +1 -9
  519. package/kits/physics-3d/engine3d/playTimings.js +50 -0
  520. package/kits/physics-3d/engine3d/playerRun.js +372 -0
  521. package/kits/physics-3d/engine3d/pxmodel.js +42 -11
  522. package/kits/physics-3d/engine3d/rapier.js +27 -0
  523. package/kits/physics-3d/engine3d/scatter.js +1 -11
  524. package/kits/physics-3d/engine3d/shadowfade.js +890 -0
  525. package/kits/physics-3d/engine3d/sky.js +547 -0
  526. package/kits/physics-3d/engine3d/skylife.js +306 -0
  527. package/kits/physics-3d/engine3d/squarefirst.js +177 -0
  528. package/kits/physics-3d/engine3d/stillshadows.js +399 -0
  529. package/kits/physics-3d/engine3d/sweep.js +1 -25
  530. package/kits/physics-3d/engine3d/unchanged.js +11 -0
  531. package/kits/physics-3d/engine3d/viewrange.js +52 -0
  532. package/kits/physics-3d/engine3d/world3d.js +1253 -76
  533. package/kits/physics-3d/eslint.config.js +2 -1
  534. package/kits/physics-3d/main.jsx +10 -2
  535. package/kits/physics-3d/package-lock.json +7 -0
  536. package/kits/physics-3d/package.json +5 -1
  537. package/kits/physics-3d/play/behaviors/Body.js +31 -0
  538. package/kits/physics-3d/play/behaviors/Door.js +37 -0
  539. package/kits/physics-3d/play/behaviors/Lookable.js +16 -0
  540. package/kits/physics-3d/play/behaviors/Model.js +23 -0
  541. package/kits/physics-3d/play/behaviors/Pickup.js +46 -0
  542. package/kits/physics-3d/play/behaviors/Player.js +1204 -0
  543. package/kits/physics-3d/play/behaviors/Shape.js +47 -0
  544. package/kits/physics-3d/play/behaviors/Solid.js +16 -0
  545. package/kits/physics-3d/play/behaviors/Transform.js +29 -0
  546. package/kits/physics-3d/pnpm-lock.yaml +8 -0
  547. package/kits/physics-3d/scripts/bench-shadow-fade.mjs +37 -0
  548. package/kits/physics-3d/scripts/build-rapier-gz.mjs +56 -0
  549. package/kits/physics-3d/scripts/frozen-statics-fixture.mjs +141 -0
  550. package/kits/physics-3d/scripts/look-baseline.mjs +155 -0
  551. package/kits/physics-3d/scripts/test-camera-follow.mjs +5 -1
  552. package/kits/physics-3d/scripts/test-camera-orbit.mjs +2613 -82
  553. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +2 -2
  554. package/kits/physics-3d/scripts/test-empty-gait-hints.mjs +89 -0
  555. package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +438 -0
  556. package/kits/physics-3d/scripts/test-frame-cap.mjs +452 -0
  557. package/kits/physics-3d/scripts/test-frozen-nested.mjs +49 -0
  558. package/kits/physics-3d/scripts/test-frozen-statics-legacy-physics2d.mjs +123 -0
  559. package/kits/physics-3d/scripts/test-frozen-statics.mjs +434 -0
  560. package/kits/physics-3d/scripts/test-gait.mjs +387 -0
  561. package/kits/physics-3d/scripts/test-look-bake.mjs +1056 -0
  562. package/kits/physics-3d/scripts/test-model-parse-cache.mjs +92 -0
  563. package/kits/physics-3d/scripts/test-near-shadows.mjs +5 -2
  564. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +2001 -0
  565. package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +582 -0
  566. package/kits/physics-3d/scripts/test-orbit-shot.mjs +657 -0
  567. package/kits/physics-3d/scripts/test-orbit-view.mjs +230 -0
  568. package/kits/physics-3d/scripts/test-rapier-gz.mjs +106 -0
  569. package/kits/physics-3d/scripts/test-skip-empty-nodes.mjs +845 -0
  570. package/kits/physics-3d/scripts/test-sky.mjs +2470 -0
  571. package/kits/physics-3d/scripts/test-square-first.mjs +921 -0
  572. package/kits/physics-3d/scripts/test-static-actors.mjs +10 -1
  573. package/kits/physics-3d/scripts/test-static-physics.mjs +4 -1
  574. package/kits/physics-3d/scripts/test-static-scenery.mjs +2174 -0
  575. package/kits/physics-3d/scripts/test-steady-hover.mjs +7 -2
  576. package/kits/physics-3d/scripts/test-still-shadows.mjs +477 -0
  577. package/kits/physics-3d/scripts/test-view-range.mjs +260 -0
  578. package/kits/physics-3d/systems/physics3d.js +419 -9
  579. package/kits/real-time/castle.json +2 -2
  580. package/kits/real-time/code/client/connection.js +33 -10
  581. package/kits/real-time/code/client/gameHooks.js +2 -0
  582. package/kits/real-time/code/client/joinOverlay.js +9 -4
  583. package/kits/real-time/code/server/gameHooks.js +7 -0
  584. package/kits/real-time/code/server/session.js +102 -22
  585. package/kits/real-time/package-lock.json +1 -1
  586. package/package.json +2 -2
  587. 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,11 +18,21 @@ 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';
27
+ import { FrozenStatics, frozenNodeState, assertFrozenEqual } from './frozenstatics.js';
24
28
  import { renderWithNearShadows, dropNearShadows } from './nearshadows.js';
29
+ import { fitOrbitLens, giveBackOrbitLens } from './orbitlens.js';
30
+ import { fitViewRange, giveBackViewRange } from './viewrange.js';
31
+ import { renderWithSky, leaveSky, skyHorizonColor } from './sky.js';
32
+ import { holdShadowFade, renderShadowFaded, dropShadowFade } from './shadowfade.js';
33
+ import { readLoadKey, actorMayWait, makeModelLoad, loadSummary, nearModelKeys,
34
+ consumerRegistryVersion, rememberModelConsumer, modelConsumerChanged } from './squarefirst.js';
35
+ export { ensureActorModel, prepareModelConsumers } from './modelready.js';
25
36
  import {
26
37
  takeModel,
27
38
  releaseModel,
@@ -104,6 +115,23 @@ export function makeWorld3D(canvas) {
104
115
  // (nearshadows.js): the shadow the engine draws for them, which is its
105
116
  // own; the sun's is never written.
106
117
  nearShadows: null,
118
+ // For scenes that set `"engine": { "sky": { ... } }` (sky.js): the sky's
119
+ // mesh, textures and fade. null unless such a scene is playing.
120
+ sky: null,
121
+ // For scenes that set `"engine": { "camera": { "follow": "rigid",
122
+ // "control": "orbit" } }` (orbitlens.js): the lens the camera had before
123
+ // the key, given back when the keyed scene goes. And for scenes with
124
+ // that key and `"shadows": { "distance": n }` (shadowfade.js): the
125
+ // world's own variants of the materials the near shadows fade out on.
126
+ orbitLens: null,
127
+ shadowFade: null,
128
+ // For scenes that set `"engine": { "look": { "bake": "deferred" } }`
129
+ // (lookbake.js): whether the scene now playing is one, and the queue of
130
+ // what is still to bake, made when the first model is built for such a
131
+ // scene. `lookBake.shown` is true once a frame has been drawn with
132
+ // nothing left to bake.
133
+ bakesLookLater: false,
134
+ lookBake: null,
107
135
  instances: new Map(),
108
136
  instanceModels: false,
109
137
  debugLines,
@@ -113,12 +141,19 @@ export function makeWorld3D(canvas) {
113
141
  }
114
142
 
115
143
  export function updatePhysicsDebug(world, buffers) {
116
- if (!buffers) return;
117
- const geometry = new THREE.BufferGeometry();
118
- geometry.setAttribute('position', new THREE.BufferAttribute(buffers.vertices, 3));
119
- geometry.setAttribute('color', new THREE.BufferAttribute(buffers.colors, 4));
120
- world.debugLines.geometry.dispose();
121
- world.debugLines.geometry = geometry;
144
+ try {
145
+ if (!buffers) return;
146
+ // Geometry disposal can run listeners outside an actor pass.
147
+ outsideCall(world, () => {
148
+ const geometry = new THREE.BufferGeometry();
149
+ geometry.setAttribute('position', new THREE.BufferAttribute(buffers.vertices, 3));
150
+ geometry.setAttribute('color', new THREE.BufferAttribute(buffers.colors, 4));
151
+ world.debugLines.geometry.dispose();
152
+ world.debugLines.geometry = geometry;
153
+ });
154
+ } catch (error) {
155
+ if (error !== EMPTY_PASS_ABORTED) throw error;
156
+ }
122
157
  }
123
158
 
124
159
  function addLights(scene) {
@@ -164,24 +199,38 @@ function addGround(scene) {
164
199
  // world size of one texture repeat (meters). The line grid only shows on the
165
200
  // untextured ground -- over art it reads as noise.
166
201
  export function syncGround(world, setting, sprites) {
202
+ try {
203
+ dressGround(world, setting, sprites);
204
+ } catch (error) {
205
+ if (error !== EMPTY_PASS_ABORTED) throw error;
206
+ }
207
+ }
208
+
209
+ // Actor passes use the throwing implementation so invalidation stops the
210
+ // pass; a deck calling syncGround gets control back without our sentinel.
211
+ function dressGround(world, setting, sprites) {
167
212
  const sig = `${JSON.stringify(setting ?? null)}|${artRefSignature(setting?.art, sprites)}`;
168
213
  if (sig === world.groundSig) return;
169
- const tile = setting?.tile > 0 ? setting.tile : 2;
170
- const repeat = [GROUND_SIZE / tile, GROUND_SIZE / tile];
171
- const texture = setting?.art ? resolveArtTexture(setting.art, sprites, repeat) : null;
172
- world.groundSig = sig;
173
- const material = new THREE.MeshStandardMaterial({
174
- color: new THREE.Color(setting?.color ?? (texture ? '#ffffff' : '#22222b')),
175
- map: texture,
176
- dithering: true,
214
+ // Also callable outside an actor pass: the old material runs listeners.
215
+ outsideCall(world, () => {
216
+ const tile = setting?.tile > 0 ? setting.tile : 2;
217
+ const repeat = [GROUND_SIZE / tile, GROUND_SIZE / tile];
218
+ const texture = setting?.art ? resolveArtTexture(setting.art, sprites, repeat) : null;
219
+ world.groundSig = sig;
220
+ const material = new THREE.MeshStandardMaterial({
221
+ color: new THREE.Color(setting?.color ?? (texture ? '#ffffff' : '#22222b')),
222
+ map: texture,
223
+ dithering: true,
224
+ });
225
+ world.ground.material.dispose();
226
+ if (world.emptyPass) checkEmptyPass(world);
227
+ world.ground.material = material;
228
+ // `"none": true`: no ground at all, drawn or stood on (the physics system
229
+ // leaves its collider out too).
230
+ const none = setting?.none === true;
231
+ world.ground.visible = !none;
232
+ world.grid.visible = !texture && !none;
177
233
  });
178
- world.ground.material.dispose();
179
- world.ground.material = material;
180
- // `"none": true`: no ground at all, drawn or stood on (the physics system
181
- // leaves its collider out too).
182
- const none = setting?.none === true;
183
- world.ground.visible = !none;
184
- world.grid.visible = !texture && !none;
185
234
  }
186
235
 
187
236
  // The signature suffix for an actor's Model component: the model file's text
@@ -206,6 +255,7 @@ function ensureActorNode(world, actor, sprites, files, drops) {
206
255
  let entry = world.nodes.get(actor.id);
207
256
  if (entry && entry.sig !== sig) {
208
257
  releaseActorNode(world, entry);
258
+ if (world.emptyPass) checkEmptyPass(world);
209
259
  entry = null;
210
260
  }
211
261
  if (!entry) {
@@ -217,6 +267,7 @@ function ensureActorNode(world, actor, sprites, files, drops) {
217
267
  entry = { node, sig };
218
268
  if (model) {
219
269
  addModelRig(world, entry, model, modelComponent, `${modelComponent.file}|${modelSig}`, {
270
+ actor,
220
271
  sprites,
221
272
  files,
222
273
  drops,
@@ -224,33 +275,86 @@ function ensureActorNode(world, actor, sprites, files, drops) {
224
275
  } else if (shape) {
225
276
  node.add(makeShapeMesh(shape, sprites));
226
277
  }
227
- world.scene.add(node);
228
- world.nodes.set(actor.id, entry);
278
+ if (world.emptyPass) {
279
+ attachEmptyActor(world, actor.id, entry);
280
+ } else {
281
+ world.scene.add(node);
282
+ world.nodes.set(actor.id, entry);
283
+ }
229
284
  }
230
285
  return entry;
231
286
  }
232
287
 
288
+ // Ownership precedes attachment only in the keyed mode: an attachment
289
+ // listener can dispose the world before scene.add has returned.
290
+ function attachEmptyActor(world, id, entry) {
291
+ checkEmptyPass(world);
292
+ world.nodes.set(id, entry);
293
+ watchEmptyNode(world, entry);
294
+ world.scene.add(entry.node);
295
+ checkEmptyPass(world);
296
+ }
297
+
233
298
  // The actor's model, from the shared build of it: a copy of its own, or,
234
299
  // for a static model in the player, a place among that model's instances.
235
- function addModelRig(world, entry, model, modelComponent, key, { sprites, files, drops }) {
300
+ function addModelRig(world, entry, model, modelComponent, key, { sprites, files, drops, actor, wait }) {
236
301
  const file = modelComponent.file;
237
302
  if (drops === true) key = `${key}|dropEmptyParts`;
238
303
  entry.modelKey = key;
239
- const template = takeModel(world.models, key, () =>
240
- buildModelNode(model, sprites, files, file, [file], { optimize: true })
241
- );
304
+ const load = world.modelLoadPass;
305
+ if (!wait && load && world.modelLoad === load && !load.restMarked && !world.instanceModels &&
306
+ !load.firstFiles.has(file) && actorMayWait(world, load.runtime, actor, load.inert) && !world.models.has(key)) {
307
+ const rig = new THREE.Group();
308
+ rig.position.y = modelComponent.yOffset ?? 0;
309
+ rig.scale.setScalar(modelComponent.scale ?? 1);
310
+ rig.userData.modelParts = new Map();
311
+ entry.node.userData.modelParts = rig.userData.modelParts;
312
+ const waiting = { load, key, entry, rig, actor, model, modelComponent, sprites, files, drops,
313
+ consumer: rememberModelConsumer(load, actor), horizonX: actor.components.Transform.x, horizonZ: actor.components.Transform.z };
314
+ entry.modelWait = waiting;
315
+ if (!load.pending.has(key)) load.pending.set(key, new Set());
316
+ load.pending.get(key).add(waiting);
317
+ load.pendingRevision++;
318
+ load.deferredKeys.add(key);
319
+ entry.node.add(rig);
320
+ return;
321
+ }
322
+ const build = () => buildModelNode(model, sprites, files, file, [file], { optimize: true });
323
+ const template = takeModel(world.models, key, world.bakesLookLater ? () => buildBakingLater(world, key, build) : build);
324
+ if (wait) {
325
+ // Building may call consumer code. A cancelled wait never owns a user.
326
+ if (entry.modelWait !== wait || world.modelLoad !== wait.load || world.disposed) {
327
+ releaseModel(world.models, key, disposeNode);
328
+ return;
329
+ }
330
+ forgetModelWait(wait);
331
+ }
332
+ const owner = wait?.load ?? (world.modelLoad === load ? load : null);
333
+ if (owner) {
334
+ owner.built.add(key);
335
+ if (!owner.synced && !wait) owner.firstKeys.add(key);
336
+ }
242
337
  if (drops === true && withoutEmptyParts(template, model).children.length === 0) {
243
338
  // A model that draws nothing has no rig; `modelParts` is there and empty.
244
- entry.node.userData.modelParts = new Map();
339
+ if (wait) entry.node.remove(wait.rig);
340
+ else entry.node.userData.modelParts = new Map();
245
341
  return;
246
342
  }
247
343
  const instanced = world.instanceModels && isStaticModel(template);
248
- const rig = instanced ? new THREE.Group() : copyModel(template);
344
+ let rig = instanced ? new THREE.Group() : copyModel(template);
345
+ if (wait) {
346
+ const parts = entry.node.userData.modelParts;
347
+ for (const [id, part] of rig.userData.modelParts) parts.set(id, part);
348
+ wait.rig.copy(rig, false);
349
+ wait.rig.userData.modelParts = parts;
350
+ while (rig.children.length) wait.rig.add(rig.children[0]);
351
+ rig = wait.rig;
352
+ }
249
353
  rig.position.y = modelComponent.yOffset ?? 0;
250
354
  const scale = modelComponent.scale ?? 1;
251
355
  rig.scale.set(scale, scale, scale);
252
356
  entry.node.userData.modelParts = rig.userData.modelParts;
253
- entry.node.add(rig);
357
+ if (!wait) entry.node.add(rig);
254
358
  if (instanced) {
255
359
  if (!world.instances.has(key)) {
256
360
  world.instances.set(key, makeInstances(template, world.scene));
@@ -258,6 +362,245 @@ function addModelRig(world, entry, model, modelComponent, key, { sprites, files,
258
362
  world.instances.get(key).rigs.add(rig);
259
363
  entry.instancedRig = rig;
260
364
  }
365
+ if (!wait && load?.pending.has(key)) fillWaitingModel(world, load, key);
366
+ }
367
+
368
+ // Waiting rigs hold no shared-build user. Only takeModel, above, acquires one.
369
+ function forgetModelWait(wait) {
370
+ const entries = wait.load.pending.get(wait.key);
371
+ if (entries?.delete(wait)) wait.load.pendingRevision++;
372
+ if (entries?.size === 0) wait.load.pending.delete(wait.key);
373
+ delete wait.entry.modelWait;
374
+ }
375
+
376
+ const loadBindings = new WeakMap();
377
+
378
+ function clearModelLoad(world) {
379
+ const load = world.modelLoad;
380
+ if (!load) return;
381
+ delete world.modelLoad;
382
+ delete world.loadQueue;
383
+ if (load.beforeBehavior && load.runtime.beforeBehavior === load.beforeBehavior) {
384
+ if (load.hadBeforeBehavior) load.runtime.beforeBehavior = load.priorBeforeBehavior;
385
+ else delete load.runtime.beforeBehavior;
386
+ }
387
+ world.modelLoadClearing = true;
388
+ leavingTheEngine(world);
389
+ // Drop incomplete nodes before a swap can park/reuse one by signature.
390
+ let failed;
391
+ try {
392
+ for (const waits of [...load.pending.values()]) {
393
+ for (const wait of [...waits]) {
394
+ world.frozenStatics?.pending.dirty.add(wait.actor);
395
+ try { releaseActorNode(world, wait.entry); } catch (error) { failed ??= { error }; }
396
+ if (world.nodes.get(wait.actor.id) === wait.entry) world.nodes.delete(wait.actor.id);
397
+ }
398
+ }
399
+ } finally {
400
+ load.pending.clear();
401
+ load.pendingRevision++;
402
+ delete world.modelLoadClearing;
403
+ }
404
+ if (failed) throw failed.error;
405
+ }
406
+
407
+ function beginModelLoad(world, runtime, sprites) {
408
+ if (world.modelLoadClearing) return null;
409
+ // The editor owns/reads arbitrary actor subtrees and renders without a
410
+ // playing runtime. Like the other static optimizations, load is play-only.
411
+ const setting = world.staticActorsOff === true ? null : readLoadKey(runtime.data);
412
+ let load = world.modelLoad;
413
+ if (load && (load.runtime !== runtime || load.data !== runtime.data ||
414
+ load.sceneKey !== (runtime.sceneKey ?? runtime.scenePath) || load.setting !== JSON.stringify(setting))) {
415
+ clearModelLoad(world);
416
+ load = null;
417
+ }
418
+ if (!setting || world.disposed) return null;
419
+ if (!load) {
420
+ load = world.modelLoad = makeModelLoad(world, runtime, setting);
421
+ load.ensureActor = id => {
422
+ const wait = world.nodes.get(id)?.modelWait;
423
+ if (!wait || wait.load !== load || world.modelLoad !== load || world.disposed ||
424
+ runtime.data !== load.data || JSON.stringify(readLoadKey(runtime.data)) !== load.setting) return;
425
+ fillWaitingModel(world, load, wait.key);
426
+ finishModelLoad(world, load);
427
+ };
428
+ load.prepareConsumers = actorId => {
429
+ if (world.modelLoad !== load || runtime.data !== load.data || world.disposed) return;
430
+ if (actorId !== undefined) {
431
+ const wait = world.nodes.get(actorId)?.modelWait;
432
+ if (wait?.load === load) checkModelConsumer(world, load, wait);
433
+ return;
434
+ }
435
+ for (const waits of load.pending.values()) for (const wait of waits) checkModelConsumer(world, load, wait);
436
+ };
437
+ if (runtime.callsBeforeBehavior === true) {
438
+ load.hadBeforeBehavior = Object.hasOwn(runtime, 'beforeBehavior');
439
+ load.priorBeforeBehavior = runtime.beforeBehavior;
440
+ load.beforeBehavior = (actor, name) => {
441
+ load.priorBeforeBehavior?.call(runtime, actor, name);
442
+ if (world.modelLoad === load && world.nodes.get(actor.id)?.modelWait &&
443
+ !actorMayWait(world, runtime, actor, load.inert)) load.ensureActor(actor.id);
444
+ };
445
+ runtime.beforeBehavior = load.beforeBehavior;
446
+ }
447
+ Object.defineProperty(world, 'loadQueue', { configurable: true, get: () => loadSummary(load, world) });
448
+ if (runtime.registerSystem && loadBindings.get(world) !== runtime) {
449
+ loadBindings.set(world, runtime);
450
+ const reset = () => { if (world.modelLoad?.runtime === runtime) clearModelLoad(world); };
451
+ runtime.registerSystem({ reset, dispose: reset });
452
+ }
453
+ }
454
+ // A sleeping/detached actor is skipped by ordinary placement. Validate its
455
+ // wait here too, so despawns/asset edits cannot fill an obsolete node.
456
+ for (const [key, waits] of [...load.pending]) {
457
+ let promote = false;
458
+ for (const wait of [...waits]) {
459
+ if (world.modelLoad !== load || wait.entry.modelWait !== wait) continue;
460
+ const actor = runtime.getActor?.(wait.actor.id) ?? runtime.getActors().find(a => a.id === wait.actor.id);
461
+ const t = actor?.components.Transform;
462
+ if (t && (t.x !== wait.horizonX || t.z !== wait.horizonZ)) {
463
+ wait.horizonX = t.x; wait.horizonZ = t.z; load.pendingRevision++;
464
+ }
465
+ const sig = waitingSignature(runtime, actor, sprites);
466
+ if (world.instanceModels || actor !== wait.actor || sig !== wait.entry.sig) {
467
+ replaceModelWait(world, load, wait, actor, sprites);
468
+ } else if (!actorMayWait(world, runtime, actor, load.inert)) {
469
+ load.firstFiles.add(actor.components.Model.file);
470
+ promote = true;
471
+ }
472
+ }
473
+ if (promote && load.pending.has(key)) fillWaitingModel(world, load, key);
474
+ }
475
+ return load;
476
+ }
477
+
478
+ function checkModelConsumer(world, load, wait) {
479
+ if (wait.entry.modelWait !== wait || world.modelLoad !== load) return;
480
+ // A previous fill can invoke a listener that registers another behaviour.
481
+ const revision = consumerRegistryVersion(load);
482
+ if (world.instanceModels || load.runtime.getActor(wait.actor.id) !== wait.actor || modelConsumerChanged(load, wait, revision)) {
483
+ load.ensureActor(wait.actor.id);
484
+ }
485
+ }
486
+
487
+ function waitingSignature(runtime, actor, sprites) {
488
+ return actor?.components.Transform && builtAs(runtime.dropsEmptyParts === true,
489
+ nodeSignature(actor, sprites, actorModelSig(actor, sprites, runtime.files)));
490
+ }
491
+
492
+ // A stale captured model cannot be filled. Rebuild through ordinary placement
493
+ // now, including sleeping roots that normal sync skips. A replacement gets
494
+ // ordinary placement's fresh attachment so tier controllers can adopt it;
495
+ // retaining an unowned detached replacement would hide it permanently.
496
+ function replaceModelWait(world, load, wait, actor, sprites) {
497
+ const current = world.nodes.get(wait.actor.id) === wait.entry;
498
+ const parent = wait.entry.node.parent;
499
+ leavingTheEngine(world);
500
+ releaseActorNode(world, wait.entry);
501
+ if (!current || world.nodes.get(wait.actor.id) !== wait.entry) return;
502
+ world.nodes.delete(wait.actor.id);
503
+ world.frozenStatics?.pending.dirty.add(actor ?? wait.actor);
504
+ if (!actor?.components.Transform || world.modelLoad !== load || world.disposed) return;
505
+ load.firstFiles.add(actor.components.Model?.file);
506
+ const entry = placeActor(world, actor, actor.components.Transform, sprites, load.runtime.files,
507
+ undefined, load.runtime.dropsEmptyParts === true);
508
+ if (parent && parent !== world.scene) outsideCall(world, () => {
509
+ entry.node.removeFromParent();
510
+ parent?.add(entry.node);
511
+ });
512
+ entry.node.updateWorldMatrix(true, true);
513
+ }
514
+
515
+ function markLoad(world, load, name) {
516
+ if (world.onStage) outsideCall(world, () => world.onStage(name, loadSummary(load, world)));
517
+ }
518
+
519
+ function finishModelLoad(world, load) {
520
+ if (load.restMarked || load.pending.size || !load.synced || world.modelLoad !== load) return;
521
+ load.restMarked = true;
522
+ markLoad(world, load, 'load:rest-built');
523
+ }
524
+
525
+ function fillWaitingModel(world, load, key) {
526
+ const waits = load.pending.get(key);
527
+ if (!waits) return;
528
+ // Invalidate static adoption before adding children, then explicitly update
529
+ // the filled subtree. FrozenStatics' event hooks rewatch it next sync.
530
+ leavingTheEngine(world);
531
+ for (const wait of [...waits]) {
532
+ if (world.modelLoad !== load || world.disposed) break;
533
+ if (wait.entry.modelWait !== wait) continue;
534
+ const actor = load.runtime.getActor ? load.runtime.getActor(wait.actor.id)
535
+ : load.runtime.getActors().find(actor => actor.id === wait.actor.id);
536
+ const sprites = load.runtime.sprites ?? wait.sprites;
537
+ if (world.nodes.get(wait.actor.id) !== wait.entry || actor !== wait.actor ||
538
+ waitingSignature(load.runtime, actor, sprites) !== wait.entry.sig) {
539
+ replaceModelWait(world, load, wait, actor, sprites);
540
+ continue;
541
+ }
542
+ world.frozenStatics?.thawActor(wait.actor);
543
+ const baseKey = wait.drops ? key.slice(0, -'|dropEmptyParts'.length) : key;
544
+ addModelRig(world, wait.entry, wait.model, wait.modelComponent, baseKey, { ...wait, wait });
545
+ if (world.modelLoad !== load || world.disposed) break;
546
+ // Preserve deliberate tier/decor detachment: only the empty-node keeper
547
+ // owns emptyDetached. Waiting rigs themselves prevent empty detachment.
548
+ wait.entry.node.updateWorldMatrix(true, true);
549
+ // Play-only engine.load notification, once per filled actor (including
550
+ // empty models). Consumers may invalidate bounds without owning the rig.
551
+ outsideCall(world, () => world.scene.dispatchEvent({
552
+ type: 'modelfilled', actorId: actor.id, node: wait.entry.node,
553
+ }));
554
+ }
555
+ }
556
+
557
+ // Compare against earlier intervals, so a single long frame does not raise
558
+ // its own threshold. Keep sampling even while all pending keys are far away.
559
+ function slowModelFrame(load, now) {
560
+ const interval = now - load.drawnAt;
561
+ load.drawnAt = now;
562
+ const sorted = [...load.frameIntervals].sort((a, b) => a - b);
563
+ const middle = sorted.length >> 1;
564
+ const median = sorted.length ? (sorted.length % 2 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2) : 0;
565
+ if (!Number.isFinite(interval) || interval < 0) return false;
566
+ load.frameIntervals.push(interval);
567
+ if (load.frameIntervals.length > 9) load.frameIntervals.shift();
568
+ return interval > Math.max(2 * median, 50);
569
+ }
570
+
571
+ function drainModelLoad(world, runtime, drawnAt) {
572
+ const load = world.modelLoad;
573
+ if (!load || load.runtime !== runtime || load.data !== runtime?.data || world.disposed || load.draining) return;
574
+ const start = load.now();
575
+ if (!load.drawn) { load.drawn = true; load.drawnAt = drawnAt; return; }
576
+ if (!load.pending.size) { finishModelLoad(world, load); return; }
577
+ const slow = slowModelFrame(load, drawnAt);
578
+ let near = nearModelKeys(world, load);
579
+ if (!near.size) { load.skippedFrames = 0; return; }
580
+ if (slow && load.skippedFrames < 3) { load.skippedFrames++; return; }
581
+ load.skippedFrames = 0;
582
+ const camera = new THREE.Vector3(), position = new THREE.Vector3();
583
+ let built = 0;
584
+ load.draining = true;
585
+ try {
586
+ while (load.pending.size && world.modelLoad === load && (!built || load.now() - start < load.sliceMs)) {
587
+ let nearestKey, nearest = Infinity;
588
+ world.camera.getWorldPosition(camera);
589
+ if (built) near = nearModelKeys(world, load);
590
+ for (const [key, waits] of load.pending) {
591
+ if (!near.has(key)) continue;
592
+ for (const wait of waits) {
593
+ wait.entry.node.getWorldPosition(position);
594
+ const distance = position.distanceToSquared(camera);
595
+ if (nearestKey === undefined || distance < nearest) { nearest = distance; nearestKey = key; }
596
+ }
597
+ }
598
+ if (nearestKey === undefined || (built && load.now() - start >= load.sliceMs)) break;
599
+ fillWaitingModel(world, load, nearestKey);
600
+ built++;
601
+ }
602
+ finishModelLoad(world, load);
603
+ } finally { load.draining = false; }
261
604
  }
262
605
 
263
606
  //
@@ -269,7 +612,7 @@ function addModelRig(world, entry, model, modelComponent, key, { sprites, files,
269
612
  // frame. For a scene that asks, a placed model is built without the groups
270
613
  // that draw nothing (optimize.js `dropEmptyGroups` has what goes and what
271
614
  // always stays), and an actor whose model draws nothing at all gets no rig
272
- // under its node. CLAUDE.md has the terms.
615
+ // under its node. docs/engine-skip-work.md has the terms.
273
616
  //
274
617
  // With the key absent nothing here runs but the tests of `drops`: a node's
275
618
  // signature, a shared build's key and the build are what they were. With it,
@@ -305,10 +648,27 @@ function builtAs(drops, sig) {
305
648
  return drops === true ? `${sig}|dropEmptyParts` : sig;
306
649
  }
307
650
 
651
+ // `build`, for a scene that asked for its models' look to be baked after they
652
+ // are drawn (lookbake.js): the baking is queued on the world as this model's.
653
+ function buildBakingLater(world, key, build) {
654
+ if (world.disposed === true) return build();
655
+ world.lookBake ??= makeLookBake();
656
+ return bakingLater(world.lookBake, key, build);
657
+ }
658
+
308
659
  // Removes an actor's node. A shared model build is given back rather than
309
660
  // disposed, since other actors may still draw it.
310
661
  function releaseActorNode(world, entry) {
662
+ const waiting = entry.modelWait;
663
+ if (waiting) forgetModelWait(waiting);
664
+ if (world.frozenStatics) {
665
+ for (const [actor, record] of world.frozenStatics.records) {
666
+ if (record.node === entry.node) { world.frozenStatics.forget(actor); break; }
667
+ }
668
+ }
669
+ if (world.emptyNodes) releaseEmptyNode(world, entry.node);
311
670
  world.scene.remove(entry.node);
671
+ if (waiting) return;
312
672
  if (!entry.modelKey) {
313
673
  disposeNode(entry.node);
314
674
  return;
@@ -330,10 +690,126 @@ const DEG = Math.PI / 180;
330
690
  // actors come and go. Dynamic bodies leave an exact quaternion in
331
691
  // `actor.runtime.quat`; everything else rotates by the Transform's euler
332
692
  // degrees.
693
+ // Worlds that never asked do not enter any empty-node lifecycle helpers.
333
694
  export function syncActors(world, runtime, sprites, dt = 0) {
695
+ if (world.modelLoadClearing) return;
696
+ // The empty-node lifecycle can deliberately reject a reentrant sync. It
697
+ // must not become the load queue's first completed actor pass either.
698
+ if ((runtime.data?.engine?.load || world.modelLoad) && world.emptyNodesOwned &&
699
+ (world.emptyNodesBlocked || world.emptyNodes?.dispatchDepth || world.emptyNodes?.draining)) {
700
+ return syncActorPass(world, runtime, sprites, dt);
701
+ }
702
+ const load = beginModelLoad(world, runtime, sprites);
703
+ if (!load && !world.modelLoadPass) return syncActorPass(world, runtime, sprites, dt);
704
+ const previous = world.modelLoadPass;
705
+ world.modelLoadPass = load;
706
+ try {
707
+ syncActorPass(world, runtime, sprites, dt);
708
+ if (load && world.modelLoad === load && !load.synced) {
709
+ // Resident nodes may already be complete without another takeModel.
710
+ for (const entry of world.nodes.values()) {
711
+ if (entry.modelKey && !entry.modelWait) {
712
+ load.built.add(entry.modelKey);
713
+ load.firstKeys.add(entry.modelKey);
714
+ }
715
+ }
716
+ load.synced = true;
717
+ markLoad(world, load, 'load:first-built');
718
+ }
719
+ if (load) finishModelLoad(world, load);
720
+ } finally {
721
+ if (previous) world.modelLoadPass = previous;
722
+ else delete world.modelLoadPass;
723
+ }
724
+ }
725
+
726
+ function syncActorPass(world, runtime, sprites, dt) {
727
+ try {
728
+ if (world.frozenStatics && (world.frozenStatics.owner !== runtime.frozenActors || world.disposed || world.staticActorsOff || world.instanceModels)) {
729
+ world.frozenStatics.dispose();
730
+ delete world.frozenStatics;
731
+ }
732
+ if (world.emptyNodesOwned) {
733
+ const state = world.emptyNodes;
734
+ if (world.disposed || world.emptyNodesBlocked || (world.emptyPass && state !== world.emptyPass)) return;
735
+ if (state && state.runtime === runtime) {
736
+ syncActorsWithEmptyNodes(world, runtime, sprites, dt, state);
737
+ return;
738
+ }
739
+ }
740
+ // A world that has held actors still, or a scene that asks to
741
+ // (`"engine": { "staticActors": true }`): the same pass, whatever its kind,
742
+ // seen in and out by the world's keeper (`syncActorsKept`, below).
743
+ if (world.stillKeeper || runtime.keepsStaticActors === true) {
744
+ syncActorsKept(world, runtime, sprites, dt);
745
+ return;
746
+ }
747
+ // Every other pass is counted while it runs, and that is all: nothing on a
748
+ // world without a keeper reads the count. It is what tells a keeper made
749
+ // from inside this pass (a callback that syncs a scene that asks) that a
750
+ // pass it never saw enter is running around it.
751
+ world.unkept = (world.unkept ?? 0) + 1;
752
+ try {
753
+ syncActorsAsEver(world, runtime, sprites, dt);
754
+ } finally {
755
+ world.unkept -= 1;
756
+ }
757
+ } catch (error) {
758
+ if (error !== EMPTY_PASS_ABORTED) throw error;
759
+ }
760
+ }
761
+
762
+ // Only the active mode pays for the bracket and chooses detached placement.
763
+ function syncActorsWithEmptyNodes(world, runtime, sprites, dt, state) {
764
+ if (state.dispatchDepth || state.draining) return;
765
+ const previous = world.emptyPass;
766
+ world.emptyPass = state;
767
+ state.depth += 1;
768
+ try {
769
+ if (state.depth === 1) syncEmptyNodes(world, state);
770
+ checkEmptyPass(world, state);
771
+ if (world.stillKeeper || runtime.keepsStaticActors === true) {
772
+ syncActorsKept(world, runtime, sprites, dt, placeEmptyActor);
773
+ } else {
774
+ world.unkept = (world.unkept ?? 0) + 1;
775
+ try { syncActorsAsEver(world, runtime, sprites, dt, placeEmptyActor); }
776
+ finally { world.unkept -= 1; }
777
+ }
778
+ } catch (error) {
779
+ if (error !== EMPTY_PASS_ABORTED) throw error;
780
+ } finally {
781
+ state.depth -= 1;
782
+ if (previous) world.emptyPass = previous;
783
+ else delete world.emptyPass;
784
+ }
785
+ }
786
+
787
+ // `syncActors` as it always was.
788
+ function skipEmptyGaitHints(world, runtime) {
789
+ return world.staticActorsOff !== true && runtime.data?.engine?.skipEmptyGaitHints === true;
790
+ }
791
+
792
+ function animateActor(world, entry, dt, actor, skipEmptyHints) {
793
+ const elapsed = animationDt(entry, dt);
794
+ if (elapsed === null) return;
795
+ animateModelParts(entry, elapsed, world.emptyPass ? world : undefined, skipEmptyHints);
796
+ if (world.emptyPass) checkEmptyPass(world);
797
+ animateMotion(entry, elapsed, actor, world.emptyPass ? world : undefined, skipEmptyHints);
798
+ if (world.emptyPass) checkEmptyPass(world);
799
+ }
800
+
801
+ // Only an opted-in, detached actor with an existing node may sleep.
802
+ // The controller checks its live Transform and wakes it before return.
803
+ function renderActorSleeps(world, actor) {
804
+ return actor.runtime?.renderSleep === true && world.nodes.has(actor.id) && !world.nodes.get(actor.id).node.parent;
805
+ }
806
+
807
+ function syncActorsAsEver(world, runtime, sprites, dt, place = placeActor) {
808
+ const skipEmptyHints = skipEmptyGaitHints(world, runtime);
334
809
  const drops = runtime.dropsEmptyParts === true;
810
+ world.bakesLookLater = runtime.bakesLookLater === true;
335
811
  if (runtime.skipsUnchangedActors === true && world.disposed !== true) {
336
- syncActorsSkipping(world, runtime, sprites, dt, drops);
812
+ syncActorsSkipping(world, runtime, sprites, dt, drops, place);
337
813
  return;
338
814
  }
339
815
  if (world.skipping.on) stopSkipping(world);
@@ -343,25 +819,23 @@ export function syncActors(world, runtime, sprites, dt = 0) {
343
819
  const key = runtime.sceneKey ?? runtime.scenePath;
344
820
  if (key !== world.scenePath) {
345
821
  swapSceneNodes(world, key, runtime.residentScenes);
822
+ if (world.emptyPass) checkEmptyPass(world);
346
823
  }
347
- syncGround(world, runtime.data?.ground, sprites);
824
+ dressGround(world, runtime.data?.ground, sprites);
825
+ if (world.emptyPass) checkEmptyPass(world);
348
826
  const seen = new Set();
349
827
  for (const actor of runtime.getActors()) {
350
828
  const t = actor.components.Transform;
351
829
  if (!t) continue;
352
830
  seen.add(actor.id);
353
- const entry = ensureActorNode(world, actor, sprites, runtime.files, drops);
354
- const node = entry.node;
355
- node.position.set(t.x, t.y, t.z);
356
- const quat = actor.runtime?.quat;
357
- if (quat) node.quaternion.set(quat.x, quat.y, quat.z, quat.w);
358
- else node.rotation.set(t.rotationX * DEG, t.rotationY * DEG, t.rotationZ * DEG);
359
- animateModelParts(entry, dt);
360
- animateMotion(entry, dt, actor);
831
+ if (renderActorSleeps(world, actor)) continue;
832
+ const entry = place(world, actor, t, sprites, runtime.files, undefined, drops);
833
+ animateActor(world, entry, dt, actor, skipEmptyHints);
361
834
  }
362
835
  for (const [id, entry] of world.nodes) {
363
836
  if (seen.has(id)) continue;
364
837
  releaseActorNode(world, entry);
838
+ if (world.emptyPass) checkEmptyPass(world);
365
839
  world.nodes.delete(id);
366
840
  }
367
841
  if (world.instances.size > 0) {
@@ -388,9 +862,12 @@ function swapSceneNodes(world, path, resident) {
388
862
  // An instanced rig is drawn by its model's shared instances wherever
389
863
  // its node is; parking it would leave it drawn in the next scene.
390
864
  releaseActorNode(world, entry);
865
+ if (world.emptyPass) checkEmptyPass(world);
391
866
  continue;
392
867
  }
868
+ if (world.emptyNodes) releaseEmptyNode(world, entry.node);
393
869
  world.scene.remove(entry.node);
870
+ if (world.emptyPass) checkEmptyPass(world);
394
871
  parked.set(id, entry);
395
872
  }
396
873
  world.parked.set(world.scenePath, parked);
@@ -404,13 +881,19 @@ function swapSceneNodes(world, path, resident) {
404
881
  for (const [id, entry] of back) {
405
882
  const current = world.nodes.get(id);
406
883
  if (current) releaseActorNode(world, current);
407
- world.scene.add(entry.node);
408
- world.nodes.set(id, entry);
884
+ if (world.emptyPass) attachEmptyActor(world, id, entry);
885
+ else {
886
+ world.scene.add(entry.node);
887
+ world.nodes.set(id, entry);
888
+ }
409
889
  }
410
890
  }
411
891
  for (const [parkedPath, parked] of world.parked) {
412
892
  if (!keep.has(parkedPath)) {
413
- for (const entry of parked.values()) releaseActorNode(world, entry);
893
+ for (const entry of parked.values()) {
894
+ releaseActorNode(world, entry);
895
+ if (world.emptyPass) checkEmptyPass(world);
896
+ }
414
897
  world.parked.delete(parkedPath);
415
898
  }
416
899
  }
@@ -418,28 +901,122 @@ function swapSceneNodes(world, path, resident) {
418
901
  }
419
902
 
420
903
  export function resizeWorld(world, width, height) {
421
- world.renderer.setSize(width, height, false);
422
- world.composer.setSize(width, height);
423
- world.camera.aspect = width / Math.max(1, height);
424
- world.camera.updateProjectionMatrix();
904
+ try {
905
+ // Resizing the composer can dispose its render targets.
906
+ outsideCall(world, () => {
907
+ world.renderer.setSize(width, height, false);
908
+ world.composer.setSize(width, height);
909
+ world.camera.aspect = width / Math.max(1, height);
910
+ world.camera.updateProjectionMatrix();
911
+ });
912
+ } catch (error) {
913
+ if (error !== EMPTY_PASS_ABORTED) throw error;
914
+ }
425
915
  }
426
916
 
427
917
  // `runtime` is given by the player, whose scene may have asked for shadows
428
918
  // near the view only (`"engine": { "shadows": { "distance": n } }`,
429
919
  // nearshadows.js). The editors give none and draw every scene the one way.
430
920
  export function renderWorld(world, runtime) {
921
+ try {
922
+ // A scene that set `"engine": { "sky": { ... } }` (sky.js), or a world with
923
+ // something left from one that did: the same frame, with the sky in the
924
+ // scene graph for as long as it takes to draw. Otherwise the frame as it
925
+ // always was.
926
+ if (runtime?.sky || world.sky) {
927
+ renderWithSky(world, runtime, drawFrame, performance.now(), skyCallFor);
928
+ } else drawFrame(world, runtime);
929
+ } catch (error) {
930
+ if (error !== EMPTY_PASS_ABORTED) throw error;
931
+ }
932
+ }
933
+
934
+ // Acquired only when the sky makes a record, not on an unowned or disposed
935
+ // world's keyed frame. A later record reuses the same callback.
936
+ function skyCallFor(world) {
937
+ return (world.skyCall ??= (fn) => outsideCall(world, fn));
938
+ }
939
+
940
+ function drawFrame(world, runtime) {
941
+ const fade = orbitFrame(world, runtime);
431
942
  // A world with nothing of the mode's, whose scene did not ask (or which is
432
943
  // being disposed): the two statements this function always was.
433
944
  const distance = runtime?.nearShadowDistance ?? 0;
434
945
  if (!world.nearShadows && !(distance > 0 && world.disposed !== true)) {
435
946
  drawWorld(world);
436
- return;
947
+ } else if (fade) {
948
+ renderShadowFaded(fade, () => drawNear(world, distance, fade, runtime));
949
+ } else {
950
+ drawNear(world, distance, undefined, runtime);
951
+ }
952
+ // Sample actual draw times, before this frame's deferred bake can delay us.
953
+ const drawnLoad = world.modelLoad;
954
+ const drawnAt = drawnLoad?.now();
955
+ // Only a world that has built a model for a scene that set
956
+ // `"engine": { "look": { "bake": "deferred" } }` has anything here.
957
+ if (world.lookBake) bakeLooks(world);
958
+ if (drawnLoad && world.modelLoad === drawnLoad) drainModelLoad(world, runtime, drawnAt);
959
+ }
960
+
961
+ // A little of the baking such a scene's models are waiting for, now that the
962
+ // frame is drawn (lookbake.js). Models nearest the camera come first, by where
963
+ // the actors placing them stood when the queue last grew. With nothing
964
+ // pending, the step only notes that the frame just drawn is the complete
965
+ // picture (`queue.shown`).
966
+ function bakeLooks(world) {
967
+ const queue = world.lookBake;
968
+ if (world.disposed === true) return;
969
+ if (queue.pending > 0 && queue.unsorted && queue.drawn) {
970
+ const nearest = new Map();
971
+ for (const entry of world.nodes.values()) {
972
+ if (!entry.modelKey) continue;
973
+ const distance = entry.node.position.distanceToSquared(world.camera.position);
974
+ if (!(distance >= nearest.get(entry.modelKey))) nearest.set(entry.modelKey, distance);
975
+ }
976
+ orderLookBake(queue, (key) => nearest.get(key) ?? Number.MAX_VALUE);
977
+ }
978
+ stepLookBake(queue);
979
+ }
980
+
981
+ // The orbit camera key's lens (orbitlens.js), on each frame of a keyed
982
+ // scene. An editor's frame (no runtime) of a world that played one gives the
983
+ // lens back. A frame of a keyless scene never looks at the camera: a load gave
984
+ // the lens back before that scene's code ran. With near shadows as well, the
985
+ // frames the near-shadow mode draws fade its far edge out (shadowfade.js, the
986
+ // fade returned); any other frame of a world that had the fade drops it.
987
+ function orbitFrame(world, runtime) {
988
+ let fade = null;
989
+ // The sky has stepped before drawFrame, so its current fade colours are
990
+ // available here. Invalid/absent view keys do not acquire any state.
991
+ if (runtime) fitViewRange(world, runtime, THREE.Fog, skyHorizonColor);
992
+ else if (world.viewRange) outsideCall(world, () => giveBackViewRange(world));
993
+ if (runtime?.cameraControl === 'orbit') {
994
+ if (world.disposed !== true) {
995
+ // Made at load (Scene3DPlayer, physics-2d's SceneRuntime.load); here
996
+ // too for a physics-2d pinned from before that, whose later loads do
997
+ // not make it. An own name tag registers on its next frame.
998
+ world.ownModelWith ??= new Set();
999
+ fitOrbitLens(world, runtime);
1000
+ fade = holdShadowFade(world, runtime);
1001
+ }
1002
+ } else if (!runtime && world.orbitLens) {
1003
+ outsideCall(world, () => giveBackOrbitLens(world));
437
1004
  }
1005
+ if (!fade && world.shadowFade) outsideCall(world, () => dropShadowFade(world));
1006
+ return fade;
1007
+ }
1008
+
1009
+ // A frame through the near-shadow mode (nearshadows.js), faded or not.
1010
+ function drawNear(world, distance, fade, runtime) {
438
1011
  renderWithNearShadows(
439
1012
  world,
440
1013
  distance,
441
1014
  () => fitShadowBias(world),
442
- () => world.composer.render()
1015
+ () => world.composer.render(),
1016
+ // Made once per world; unchanged frames neither call nor allocate it.
1017
+ (world.nearShadowCall ??= (fn) => outsideCall(world, fn)),
1018
+ fade,
1019
+ runtime
443
1020
  );
444
1021
  }
445
1022
 
@@ -472,24 +1049,61 @@ function fitShadowBias(world) {
472
1049
  }
473
1050
 
474
1051
  export function disposeWorld(world) {
475
- // Releasing a node runs `dispose` listeners, which may sync this world
476
- // again. From here on it never skips (`syncActors` reads `disposed`), so
477
- // such a sync writes nothing down; what was written down before goes now,
478
- // and again after the listeners have run, whether or not one throws.
479
- world.disposed = true;
480
- // A `dispose` listener on the near-shadow mode's map that throws does not
481
- // keep the rest from being released.
482
1052
  try {
483
- dropNearShadows(world);
484
- } finally {
485
- disposeNodes(world);
1053
+ // Releasing a node runs `dispose` listeners, which may sync this world
1054
+ // again. From here on it never skips (`syncActors` reads `disposed`), so
1055
+ // such a sync writes nothing down; what was written down before goes now,
1056
+ // and again after the listeners have run, whether or not one throws.
1057
+ world.disposed = true;
1058
+ if (world.frozenStatics) {
1059
+ world.frozenStatics.dispose();
1060
+ delete world.frozenStatics;
1061
+ }
1062
+ // With no keeper this is counted by `unkept`, just like a plain sync.
1063
+ outsideCall(world, () => {
1064
+ // Every cleanup runs even when an earlier one throws. Keep the first
1065
+ // thrown value (including a falsy one) through all five stages.
1066
+ let first = null;
1067
+ const clean = (fn) => {
1068
+ try { fn(); } catch (err) { first ??= { err }; }
1069
+ };
1070
+ if (world.modelLoad) clean(() => clearModelLoad(world));
1071
+ try {
1072
+ clean(() => giveBackOrbitLens(world));
1073
+ if (world.viewRange) clean(() => giveBackViewRange(world));
1074
+ } finally {
1075
+ try {
1076
+ // The sky's record (skylife.js): disposed now, or by the frame in
1077
+ // progress on its way out; a `dispose` listener's error comes back.
1078
+ clean(() => {
1079
+ const failed = world.sky ? leaveSky(world) : null;
1080
+ if (failed !== null) throw failed;
1081
+ });
1082
+ } finally {
1083
+ try {
1084
+ clean(() => dropShadowFade(world));
1085
+ } finally {
1086
+ try {
1087
+ clean(() => dropNearShadows(world));
1088
+ } finally {
1089
+ clean(() => disposeNodes(world));
1090
+ }
1091
+ }
1092
+ }
1093
+ }
1094
+ if (first !== null) throw first.err;
1095
+ });
1096
+ } catch (error) {
1097
+ if (error !== EMPTY_PASS_ABORTED) throw error;
486
1098
  }
487
1099
  }
488
1100
 
489
1101
  function disposeNodes(world) {
1102
+ if (world.emptyNodesOwned) forgetEmptyNodes(world);
490
1103
  world.skipping.on = false;
491
1104
  leavingTheEngine(world);
492
1105
  forgetEverything(world);
1106
+ if (world.lookBake) clearLookBake(world.lookBake);
493
1107
  try {
494
1108
  for (const entry of world.nodes.values()) releaseActorNode(world, entry);
495
1109
  world.nodes.clear();
@@ -559,7 +1173,7 @@ function disposeNodes(world) {
559
1173
  // and `files` tables, `runtime.getActors`, three.js math, and building
560
1174
  // signatures from plain data (`JSON.stringify` calls no one for those). A
561
1175
  // scene whose components are not plain stored data is outside the key's terms
562
- // (CLAUDE.md).
1176
+ // (docs/engine-skip-work.md).
563
1177
  //
564
1178
  // What is written down, and where:
565
1179
  // - `world.snapshots`, a WeakMap from a node entry to what the node was built
@@ -587,6 +1201,10 @@ const MODEL_SIGS_LIMIT = 512;
587
1201
  // that is not the engine's. See the list above.
588
1202
  function leavingTheEngine(world) {
589
1203
  world.generation += 1;
1204
+ if (world.frozenStatics) world.frozenStatics.invalidate();
1205
+ // And nothing is frozen while code that is not the engine's runs inside a
1206
+ // pass (only a world that holds actors still has anything here).
1207
+ if (world.stillKeeper) dropStill(world);
590
1208
  }
591
1209
 
592
1210
  // The scene now playing did not ask: every node is a plain Group again and
@@ -607,6 +1225,7 @@ function forgetSnapshots(world) {
607
1225
  // And what each node, playing or parked, remembers of its own matrices.
608
1226
  function forgetEverything(world) {
609
1227
  forgetSnapshots(world);
1228
+ if (world.stillKeeper) dropStill(world);
610
1229
  const forget = (entry) => {
611
1230
  if (entry.node.computedFrom) entry.node.computedFrom = null;
612
1231
  };
@@ -614,7 +1233,7 @@ function forgetEverything(world) {
614
1233
  for (const parked of world.parked.values()) parked.forEach(forget);
615
1234
  }
616
1235
 
617
- function syncActorsSkipping(world, runtime, sprites, dt, drops) {
1236
+ function syncActorsSkipping(world, runtime, sprites, dt, drops, place = placeActor) {
618
1237
  // Entered while a pass is running: that pass is no longer alone.
619
1238
  if (world.syncDepth > 0) leavingTheEngine(world);
620
1239
  const outermost = world.syncDepth === 0;
@@ -623,7 +1242,7 @@ function syncActorsSkipping(world, runtime, sprites, dt, drops) {
623
1242
  world.syncDepth += 1;
624
1243
  let finished = false;
625
1244
  try {
626
- skippingPass(world, runtime, sprites, dt, outermost ? started : -1, drops);
1245
+ skippingPass(world, runtime, sprites, dt, outermost ? started : -1, drops, undefined, place);
627
1246
  finished = true;
628
1247
  } finally {
629
1248
  world.syncDepth -= 1;
@@ -633,20 +1252,26 @@ function syncActorsSkipping(world, runtime, sprites, dt, drops) {
633
1252
 
634
1253
  // One pass. `started` is the generation it may trust its state at; a pass
635
1254
  // entered inside another is given one that never matches.
636
- function skippingPass(world, runtime, sprites, dt, started, drops) {
1255
+ function skippingPass(world, runtime, sprites, dt, started, drops, pass, place = placeActor) {
1256
+ const skipEmptyHints = skipEmptyGaitHints(world, runtime);
637
1257
  beginPass(world, runtime, sprites);
1258
+ if (world.emptyPass) checkEmptyPass(world);
638
1259
  if (world.generation === started) {
639
1260
  world.syncCount += 1;
640
1261
  world.sigEpoch += 1;
641
1262
  }
1263
+ if (pass !== undefined) {
1264
+ // `syncActorsHoldingStill`'s pass: settled, or ordinary from here.
1265
+ if (staysSettled(world, runtime, sprites, started, drops, pass)) return settledPass(world, runtime, sprites, dt, started, drops, place);
1266
+ }
642
1267
  const seen = new Set();
643
1268
  for (const actor of runtime.getActors()) {
644
1269
  const t = actor.components.Transform;
645
1270
  if (!t) continue;
646
1271
  seen.add(actor.id);
647
- const entry = placeActor(world, actor, t, sprites, runtime.files, started, drops);
648
- animateModelParts(entry, dt);
649
- animateMotion(entry, dt, actor);
1272
+ if (renderActorSleeps(world, actor)) continue;
1273
+ const entry = place(world, actor, t, sprites, runtime.files, started, drops);
1274
+ animateActor(world, entry, dt, actor, skipEmptyHints);
650
1275
  }
651
1276
  // While the pass was alone every actor seen has its node and no node was
652
1277
  // released, so as many nodes as actors seen means no node has lost its actor.
@@ -666,11 +1291,12 @@ function beginPass(world, runtime, sprites) {
666
1291
  if (key !== world.scenePath) {
667
1292
  leavingTheEngine(world);
668
1293
  swapSceneNodes(world, key, runtime.residentScenes);
1294
+ if (world.emptyPass) checkEmptyPass(world);
669
1295
  }
670
1296
  const setting = runtime.data?.ground;
671
1297
  if (!groundIsDressed(world, setting, sprites)) {
672
1298
  leavingTheEngine(world);
673
- syncGround(world, setting, sprites);
1299
+ dressGround(world, setting, sprites);
674
1300
  }
675
1301
  if (typeof world.scene.userData.groundHeight === 'function' || world.instanceModels || world.instances.size > 0) {
676
1302
  leavingTheEngine(world);
@@ -688,7 +1314,8 @@ function groundIsDressed(world, setting, sprites) {
688
1314
  // once it is not.
689
1315
  function placeActor(world, actor, t, sprites, files, started, drops) {
690
1316
  const alone = world.generation === started;
691
- const entry = alone ? nodeFor(world, actor, sprites, files, drops) : nodeAsMain(world, actor, sprites, files, drops);
1317
+ const entry = started === undefined ? ensureActorNode(world, actor, sprites, files, drops)
1318
+ : alone ? nodeFor(world, actor, sprites, files, drops) : nodeAsMain(world, actor, sprites, files, drops);
692
1319
  const node = entry.node;
693
1320
  node.position.set(t.x, t.y, t.z);
694
1321
  const quat = actor.runtime?.quat;
@@ -697,16 +1324,47 @@ function placeActor(world, actor, t, sprites, files, started, drops) {
697
1324
  else node.rotation.set(t.rotationX * DEG, t.rotationY * DEG, t.rotationZ * DEG);
698
1325
  // A node moved under something with a ground-height callback of its own,
699
1326
  // which animating it is about to call.
700
- if (node.parent !== world.scene && typeof node.parent?.userData?.groundHeight === 'function') {
1327
+ if (started !== undefined && node.parent !== world.scene && typeof node.parent?.userData?.groundHeight === 'function') {
701
1328
  leavingTheEngine(world);
702
1329
  }
703
1330
  return entry;
704
1331
  }
705
1332
 
1333
+ function placeEmptyActor(world, actor, transform, sprites, files, started, drops) {
1334
+ const found = started === undefined ? ensureActorNode(world, actor, sprites, files, drops)
1335
+ : world.generation === started ? nodeFor(world, actor, sprites, files, drops)
1336
+ : nodeAsMain(world, actor, sprites, files, drops);
1337
+ checkEmptyPass(world);
1338
+ putEmptyActor(found.node, transform, actor.runtime?.quat,
1339
+ world.generation === started ? snapshotOf(world, found) : null);
1340
+ checkEmptyPass(world);
1341
+ if (typeof found.node.parent?.userData?.groundHeight === 'function' && found.node.parent !== world.scene) leavingTheEngine(world);
1342
+ return found;
1343
+ }
1344
+
1345
+ function putEmptyActor(node, t, quat, snapshot = null) {
1346
+ const detached = node.emptyDetached && !node.parent && node.children.length === 0;
1347
+ const p = node.position;
1348
+ const q = node.quaternion;
1349
+ const moved = detached && (!Object.is(p.x, t.x) || !Object.is(p.y, t.y) || !Object.is(p.z, t.z));
1350
+ // Direct consumer writes on empty detached roots are outside the contract.
1351
+ // Comparing the quaternion here covers both Euler and physics placement.
1352
+ const x = q.x, y = q.y, z = q.z, w = q.w;
1353
+ p.set(t.x, t.y, t.z);
1354
+ if (snapshot) turnNode(snapshot, node, t, quat);
1355
+ else if (quat) q.set(quat.x, quat.y, quat.z, quat.w);
1356
+ else {
1357
+ const rx = t.rotationX * DEG, ry = t.rotationY * DEG, rz = t.rotationZ * DEG;
1358
+ if (!detached || node.rotation.x !== rx || node.rotation.y !== ry || node.rotation.z !== rz) node.rotation.set(rx, ry, rz);
1359
+ }
1360
+ 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);
1361
+ }
1362
+
706
1363
  function releaseUnseen(world, seen) {
707
1364
  for (const [id, entry] of world.nodes) {
708
1365
  if (seen.has(id)) continue;
709
1366
  releaseNode(world, entry);
1367
+ if (world.emptyPass) checkEmptyPass(world);
710
1368
  world.nodes.delete(id);
711
1369
  }
712
1370
  }
@@ -843,11 +1501,19 @@ function snapshotOf(world, entry) {
843
1501
  function buildNode(world, old, actor, sig, modelSig, sprites, files, drops) {
844
1502
  leavingTheEngine(world);
845
1503
  if (old) releaseNode(world, old);
1504
+ if (world.emptyPass) checkEmptyPass(world);
846
1505
  const entry = { node: new ActorNode(world.skipping), sig };
847
1506
  entry.node.userData.actorId = actor.id;
848
1507
  fillNode(world, entry, actor, modelSig, sprites, files, drops);
849
- world.scene.add(entry.node);
850
- world.nodes.set(actor.id, entry);
1508
+ if (world.emptyPass) {
1509
+ attachEmptyActor(world, actor.id, entry);
1510
+ } else {
1511
+ // A frozen pass retries a failed batch. Own an attached node even when a
1512
+ // childadded listener throws, so retrying cannot leave a visible orphan.
1513
+ if (world.frozenStatics) world.nodes.set(actor.id, entry);
1514
+ world.scene.add(entry.node);
1515
+ world.nodes.set(actor.id, entry);
1516
+ }
851
1517
  return entry;
852
1518
  }
853
1519
 
@@ -855,7 +1521,7 @@ function fillNode(world, entry, actor, modelSig, sprites, files, drops) {
855
1521
  const { Model: placed, Shape: shape } = actor.components;
856
1522
  const model = placed?.file ? parseModelCached(files?.[placed.file]) : null;
857
1523
  if (model) {
858
- addModelRig(world, entry, model, placed, `${placed.file}|${modelSig}`, { sprites, files, drops });
1524
+ addModelRig(world, entry, model, placed, `${placed.file}|${modelSig}`, { sprites, files, drops, actor });
859
1525
  } else if (shape) {
860
1526
  entry.node.add(makeShapeMesh(shape, sprites));
861
1527
  }
@@ -896,3 +1562,514 @@ function sameTurn(r, x, y, z) {
896
1562
  function sameQuaternion(q, was) {
897
1563
  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);
898
1564
  }
1565
+
1566
+ //
1567
+ // Scenes that set `"engine": { "staticActors": true }`
1568
+ //
1569
+ // With `skipUnchangedActors` a pass still asks, of every actor on every frame,
1570
+ // whether anything it is drawn from has changed. For scenery that never
1571
+ // changes, the asking is the cost. A scene that also sets `staticActors` marks
1572
+ // such actors in its file (`"static": true` on the actor), its runtime holds
1573
+ // them still (physics-2d engine/scene.js: `stillActors`, `stillVersion`,
1574
+ // `touch`), and this world leaves them out of its pass and freezes their nodes
1575
+ // (actornode.js). docs/engine-static-actors.md has the terms. The rule:
1576
+ //
1577
+ // A pass is ORDINARY (every actor, as the skipping pass above runs it)
1578
+ // unless the still set and the things its actors share read as they did
1579
+ // when the last ordinary pass that ended alone adopted them; then it is
1580
+ // SETTLED, and a still actor is left exactly as that pass left it.
1581
+ //
1582
+ // The still set is adopted only AFTER an ordinary pass has completed
1583
+ // without throwing. While any pass, or anything it calls back into, is
1584
+ // running, nothing is frozen and no still state is trusted. Any
1585
+ // interruption -- a throw, a pass entered from inside another, by this
1586
+ // runtime or any other -- leaves the next pass ordinary.
1587
+ //
1588
+ // The second paragraph is one mechanism, the same in the runtime's update,
1589
+ // here and in the physics system: a StillKeeper (physics-2d
1590
+ // engine/stillClock.js has it and the reasoning), handed out by the runtime
1591
+ // (`newStillKeeper`) and kept as `world.stillKeeper`. Nothing about an
1592
+ // adoption is kept anywhere else. What this world adds to it:
1593
+ // - the keeper counts an entry at the top of `syncActorsHoldingStill`,
1594
+ // before anything else; `dropStill` reports to it (`interrupt`) from
1595
+ // `leavingTheEngine`, which the engine calls before anything in a pass can
1596
+ // run code that is not its own (a node built or released, a scene change,
1597
+ // the ground dressed anew, a callback, a pass entered from inside
1598
+ // another), and from a frame without the key and a dispose;
1599
+ // - `thaw` moves `skipping.epoch`, which unfreezes every node at once: before
1600
+ // an ordinary pass visits its first actor, with every `dropStill`, and on
1601
+ // the way out of any pass that leaves nothing adopted. So a listener or
1602
+ // callback that walks the scene, draws it or syncs it from inside a pass,
1603
+ // settled or not, finds every node an ordinary ActorNode;
1604
+ // - the pass is `completed`, to the keeper, only if it was outermost,
1605
+ // returned, and was alone to its end by the generation; `adoptStill` is
1606
+ // what the keeper calls, last, when it will keep what it returns.
1607
+ //
1608
+ // What makes a pass that began settled ordinary (`staysSettled`), each asked
1609
+ // at its start, after `beginPass`, and never worked out afterwards:
1610
+ // - the keeper's count or the runtime's `stillVersion` has moved since the
1611
+ // pass began (the audit touched an actor);
1612
+ // - `skipping.epoch` is not the one adopted at, or the scene builds its
1613
+ // models the other way (`drops`);
1614
+ // - any model file a still actor places (or a file or art that model reads,
1615
+ // or the look switch, which is part of every model file's signature and
1616
+ // of nothing else a node is built from), or any art a still actor's Shape
1617
+ // names reads differently: one check a file and one an art, not one an
1618
+ // actor;
1619
+ // - (not the scene's own place: a frozen node asks, on every walk, whether
1620
+ // its parent's world matrix is the one it was frozen under, and computes
1621
+ // itself again when it is not: actornode.js.)
1622
+ // Between passes nothing here is asked: a frozen node thaws by itself the
1623
+ // moment any scene's still set changes (`skipping.clock`).
1624
+ // A settled pass that stops being alone part way (a live actor's node is
1625
+ // built, a callback syncs another scene) places every actor it has not yet
1626
+ // passed the way `syncActors` does, still ones included, in the same order.
1627
+ //
1628
+ // What is written down, and where:
1629
+ // - `world.stillKeeper`: its count, and its adoption, to which this world
1630
+ // adds the epoch adopted at, the version the Set was made at (for the
1631
+ // audit), how many still actors have a node, and what the shared things
1632
+ // read as: numbers and strings, and the art objects read, which the deck's
1633
+ // `sprites` table holds anyway. It refers to no actor, no node and no
1634
+ // runtime.
1635
+ // - `world.skipping.epoch`, `clock` and `clockAt`: two numbers and the
1636
+ // runtime's `stillClock` function (it reads a module's counter).
1637
+ // - on a still actor's node, `freezes` and `frozenAt`: numbers (actornode.js).
1638
+ //
1639
+ // A world that must never hold anything still (the scene editor's) sets
1640
+ // `world.staticActorsOff`; it, and a world with `instanceModels`, tells the
1641
+ // runtime so after its first pass (`releaseStill`), and from then on no actor
1642
+ // of the scene is still for anyone. A scene with a ground-height callback is
1643
+ // never alone, so this world never adopts and never freezes a node there; the
1644
+ // update loop and the physics system, which call nothing in the middle of
1645
+ // their work, still leave its still actors out.
1646
+ //
1647
+ // `world.auditStatic = n` (QA only; nothing sets it in play): each pass that
1648
+ // finds its runtime's still set as it was adopted (less what has been touched
1649
+ // since), and what its actors share as it was (a model file edited or the
1650
+ // look switched is no fault of an actor's), first
1651
+ // checks `n` of its actors, in turn, the way an ordinary pass would have, and one found changed is written
1652
+ // to `world.staticAuditFailures`, warned of once and touched (so that pass is
1653
+ // an ordinary one). The physics system does the same for every still body.
1654
+ // With `n` at least the number of still actors, every pass is a checked one.
1655
+
1656
+ // Every frozen node of the world is an ordinary ActorNode again from its next
1657
+ // walk: the epoch they froze at is not the epoch any more.
1658
+ function thaw(world) {
1659
+ world.skipping.epoch = (world.skipping.epoch ?? 0) + 1;
1660
+ }
1661
+
1662
+ // Something is about to run that the world's pass count does not see by
1663
+ // itself (`leavingTheEngine`, a frame without the key, a dispose): nothing
1664
+ // stays adopted, whatever pass is running will not adopt, and nothing stays
1665
+ // frozen.
1666
+ function dropStill(world) {
1667
+ world.stillKeeper.interrupt();
1668
+ thaw(world);
1669
+ }
1670
+
1671
+ // Keep the entire call-out counted, including every listener and re-entry.
1672
+ // Nested syncs cannot adopt while `running` includes this non-adopting pass.
1673
+ // Before a keeper exists, `unkept` counts the entry exactly as `syncActors`
1674
+ // does, so a keeper made by a listener sees the operation running around it.
1675
+ function outsideCall(world, fn) {
1676
+ const keeper = world.stillKeeper;
1677
+ if (!keeper) {
1678
+ world.unkept = (world.unkept ?? 0) + 1;
1679
+ try {
1680
+ return fn();
1681
+ } finally {
1682
+ world.unkept -= 1;
1683
+ if (world.stillKeeper) dropStill(world);
1684
+ }
1685
+ }
1686
+ const pass = keeper.begin(NOT_STILL);
1687
+ try {
1688
+ dropStill(world);
1689
+ return fn();
1690
+ } finally {
1691
+ keeper.end(pass, false);
1692
+ }
1693
+ }
1694
+
1695
+ // `syncActors` for a world with a keeper, or a scene that asks for one. The
1696
+ // invariant, which is about entry points and not about kinds of pass:
1697
+ //
1698
+ // From the moment a world has a keeper, the keeper sees EVERY entry into
1699
+ // and exit from `syncActors` on that world, of every kind (plain, skipping,
1700
+ // instanced, the editor's, settled, ordinary; any runtime). An adoption can
1701
+ // be recorded only by a pass that was alone from its entry to its exit, and
1702
+ // any pass of any kind that enters, or is running, drops it.
1703
+ //
1704
+ // `syncActors` is the one function through which the nodes of a world are
1705
+ // built, placed, parked, swapped and released (`swapSceneNodes`,
1706
+ // `ensureActorNode`, `buildNode`, `releaseUnseen`, the instanced draw are all
1707
+ // reached only from it); `disposeWorld`, the other, reports to the keeper and
1708
+ // leaves a world that never adopts again. So bracketing `syncActors` here is
1709
+ // bracketing every one of them.
1710
+ // - A pass that holds nothing still (its scene did not ask for
1711
+ // `staticActors`, or not with `skipUnchangedActors`, or the world is
1712
+ // disposed) is counted in, drops whatever was adopted before it does
1713
+ // anything, thaws (a skipping pass of a scene that does not ask would
1714
+ // otherwise place nodes that stay frozen), runs as it always did, and
1715
+ // never adopts on its way out.
1716
+ // - A pass of a scene that asks is `syncActorsHoldingStill`.
1717
+ // - A pass that entered BEFORE the world had a keeper was not seen entering.
1718
+ // `world.unkept` counts those while they run; a keeper is only ever made
1719
+ // from inside one (or with none running), and while the count is not zero
1720
+ // no pass is settled and none adopts.
1721
+ function syncActorsKept(world, runtime, sprites, dt, place = placeActor) {
1722
+ if (runtime.freezesStatics === true && !world.disposed && !world.staticActorsOff && !world.instanceModels) {
1723
+ syncFrozenActors(world, runtime, sprites, dt, place);
1724
+ return;
1725
+ }
1726
+ const keeper = (world.stillKeeper ??= runtime.newStillKeeper());
1727
+ if (runtime.keepsStaticActors === true && world.disposed !== true) {
1728
+ world.bakesLookLater = runtime.bakesLookLater === true;
1729
+ syncActorsHoldingStill(world, runtime, sprites, dt, runtime.dropsEmptyParts === true, place);
1730
+ return;
1731
+ }
1732
+ const pass = keeper.begin(NOT_STILL);
1733
+ thaw(world);
1734
+ try {
1735
+ syncActorsAsEver(world, runtime, sprites, dt, place);
1736
+ } finally {
1737
+ keeper.end(pass, false);
1738
+ }
1739
+ }
1740
+
1741
+ // The new opt-in never filters the full actor list on an unchanged frame.
1742
+ // Writes feed this world's queue; live/fallback actors retain the old checks.
1743
+ function syncFrozenActors(world, runtime, sprites, dt, place) {
1744
+ const state = world.frozenStatics ??= new FrozenStatics(world, runtime);
1745
+ if (world.syncDepth > 0) {
1746
+ state.invalidate();
1747
+ syncActorsSkipping(world, runtime, sprites, dt, runtime.dropsEmptyParts === true, place);
1748
+ return;
1749
+ }
1750
+ const drops = runtime.dropsEmptyParts === true;
1751
+ world.skipping.on = true;
1752
+ world.bakesLookLater = runtime.bakesLookLater === true;
1753
+ world.syncDepth++;
1754
+ let finished = false;
1755
+ let actors = [];
1756
+ try {
1757
+ beginPass(world, runtime, sprites);
1758
+ if (world.frozenStatics !== state) return;
1759
+ world.syncCount++;
1760
+ world.sigEpoch++;
1761
+ state.assets ??= new Map();
1762
+ state.arts ??= new Map();
1763
+ const shared = `${drops}|${lookIsEnabled()}`;
1764
+ let changed = shared !== state.shared;
1765
+ state.shared = shared;
1766
+ for (const [file, was] of state.assets) {
1767
+ const now = modelSigOf(world, file, sprites, runtime.files);
1768
+ if (now !== was) changed = true;
1769
+ state.assets.set(file, now);
1770
+ }
1771
+ for (const [art, was] of state.arts) {
1772
+ const now = artRefSignature(art, sprites);
1773
+ if (now !== was) changed = true;
1774
+ state.arts.set(art, now);
1775
+ }
1776
+ if (changed) state.invalidate();
1777
+ actors = state.take();
1778
+ const skipHints = skipEmptyGaitHints(world, runtime);
1779
+ const started = world.generation;
1780
+ for (const actor of actors) {
1781
+ if (world.frozenStatics !== state) return;
1782
+ const t = actor.components.Transform;
1783
+ if (runtime.getActor(actor.id) !== actor || runtime.isActorSleeping(actor) || !t) {
1784
+ if (runtime.getActor(actor.id) && runtime.getActor(actor.id) !== actor) { state.forget(actor); continue; }
1785
+ const entry = world.nodes.get(actor.id);
1786
+ if (entry) { releaseNode(world, entry); world.nodes.delete(actor.id); }
1787
+ state.forget(actor);
1788
+ continue;
1789
+ }
1790
+ if (renderActorSleeps(world, actor)) continue;
1791
+ state.thawActor(actor);
1792
+ const entry = place(world, actor, t, sprites, runtime.files, started, drops);
1793
+ animateActor(world, entry, dt, actor, skipHints);
1794
+ if (world.frozenStatics !== state) return;
1795
+ if (movesInside(world, entry) || typeof world.scene.userData.groundHeight === 'function') state.live.add(actor);
1796
+ else state.freeze(actor, entry);
1797
+ const file = actor.components.Model?.file;
1798
+ if (file) state.rememberAsset(actor, 'assets', file, world.generation === started ? modelSigOf(world, file, sprites, runtime.files) : actorModelSig(actor, sprites, runtime.files));
1799
+ const art = actor.components.Shape?.art;
1800
+ for (const ref of typeof art === 'string' ? [art] : Object.values(art ?? {})) {
1801
+ if (typeof ref === 'string') state.rememberAsset(actor, 'arts', ref, artRefSignature(ref, sprites));
1802
+ }
1803
+ if (world.frozenStaticVisits) world.frozenStaticVisits(actor);
1804
+ }
1805
+ // A new owner may reuse nodes at the same path, or inherit unparked nodes
1806
+ // from another scene. Reconcile that baseline once, as the full pass does.
1807
+ if (state.reconcileNodes) {
1808
+ const seen = new Set(runtime.getActors().filter(actor => actor.components.Transform).map(actor => actor.id));
1809
+ releaseUnseen(world, seen);
1810
+ if (world.frozenStatics !== state) return;
1811
+ state.reconcileNodes = false;
1812
+ }
1813
+ if (world.auditFrozenStatics === true) {
1814
+ world.scene.updateMatrixWorld();
1815
+ const before = frozenNodeState(world);
1816
+ state.invalidate();
1817
+ // QA only: perform the full old unchanged/signature/matrix walk, and
1818
+ // assert it cannot alter the frozen frame's node state.
1819
+ for (const actor of runtime.getActors()) {
1820
+ if (actor.components.Transform && !renderActorSleeps(world, actor)) {
1821
+ place(world, actor, actor.components.Transform, sprites, runtime.files, world.generation, drops);
1822
+ }
1823
+ }
1824
+ world.scene.updateMatrixWorld();
1825
+ assertFrozenEqual(before, frozenNodeState(world), 'node matrices/signatures');
1826
+ }
1827
+ finished = true;
1828
+ } finally {
1829
+ world.syncDepth--;
1830
+ if (!finished && world.frozenStatics === state) {
1831
+ for (const actor of actors) state.pending.dirty.add(actor);
1832
+ state.invalidate();
1833
+ forgetSnapshots(world);
1834
+ }
1835
+ }
1836
+ }
1837
+
1838
+ // The version a pass that holds nothing still begins with: no still set's.
1839
+ const NOT_STILL = -1;
1840
+
1841
+ // `syncActorsSkipping` for a scene that holds actors still: the same
1842
+ // statements, as one pass to the world's keeper (physics-2d
1843
+ // engine/stillClock.js has the rule). The keeper counts this entry before the
1844
+ // pass does anything; an ordinary pass thaws before its first actor; the pass
1845
+ // adopts only on its way out, and only if it was outermost, returned, was
1846
+ // alone to its end (no callout, by the generation), nobody entered meanwhile
1847
+ // (by the keeper's count), no pass the keeper never saw is running
1848
+ // (`world.unkept`), and the still set is the one it began with.
1849
+ function syncActorsHoldingStill(world, runtime, sprites, dt, drops, place) {
1850
+ const keeper = world.stillKeeper;
1851
+ if (world.syncDepth > 0) leavingTheEngine(world);
1852
+ const outermost = world.syncDepth === 0;
1853
+ const started = world.generation;
1854
+ world.skipping.on = true;
1855
+ world.syncDepth += 1;
1856
+ const audited = world.auditStatic > 0 ? adoptedForAudit(world) : null;
1857
+ const pass = keeper.begin(runtime.stillVersion);
1858
+ pass.audited = audited;
1859
+ // A pass the keeper never saw enter is running around this one.
1860
+ if (pass.settled && world.unkept > 0) keeper.demote(pass);
1861
+ if (!pass.settled) thaw(world);
1862
+ let finished = false;
1863
+ try {
1864
+ skippingPass(world, runtime, sprites, dt, outermost ? started : -1, drops, pass, place);
1865
+ finished = true;
1866
+ } finally {
1867
+ world.syncDepth -= 1;
1868
+ const alone = outermost && finished && world.generation === started;
1869
+ if (outermost && !alone) forgetSnapshots(world);
1870
+ endStillPass(world, runtime, pass, alone && !(world.unkept > 0), drops);
1871
+ }
1872
+ }
1873
+
1874
+ // The way out of `syncActorsHoldingStill`'s pass, whether it returned or threw.
1875
+ function endStillPass(world, runtime, pass, alone, drops) {
1876
+ const keeper = world.stillKeeper;
1877
+ // A world that holds nothing still says so to the runtime, so that the
1878
+ // update loop and the physics system hold nothing still either.
1879
+ if ((world.staticActorsOff === true || world.instanceModels === true) && runtime.stillActors?.size > 0) runtime.releaseStill();
1880
+ keeper.end(pass, alone, runtime.stillVersion, () => adoptStill(world, runtime, drops));
1881
+ if (keeper.adopted === null) thaw(world);
1882
+ }
1883
+
1884
+ // For the audit only (QA): what was adopted as a pass begins, if it was good
1885
+ // until then, and the epoch it was good at. Nothing is left out of a pass on
1886
+ // its word.
1887
+ function adoptedForAudit(world) {
1888
+ const keeper = world.stillKeeper;
1889
+ return keeper.adopted?.at === keeper.passes ? { ...keeper.adopted, epochNow: world.skipping.epoch } : null;
1890
+ }
1891
+
1892
+ // Whether a pass that began settled may stay so, asked after `beginPass` (a
1893
+ // scene change or a ground dressed anew has already been reported): nothing
1894
+ // has entered or been reported since it began, the adoption is of this epoch
1895
+ // and this way of building, and what the still actors share reads as it did.
1896
+ // The audit, if asked for, looks first, and what it finds touched makes the
1897
+ // pass ordinary. A pass that may not stay settled is ordinary from here:
1898
+ // nothing adopted, nothing frozen, before its first actor.
1899
+ function staysSettled(world, runtime, sprites, started, drops, pass) {
1900
+ if (pass.audited && isAuditable(world, runtime, sprites, started, drops, pass.audited)) auditStill(world, runtime, sprites, drops, pass.audited);
1901
+ if (pass.settled && isAsAdopted(world, runtime, sprites, started, drops, pass)) return true;
1902
+ if (pass.settled) world.stillKeeper.demote(pass);
1903
+ thaw(world);
1904
+ return false;
1905
+ }
1906
+
1907
+ // Whether the audit has anything to say this pass: what was adopted is of the
1908
+ // runtime's still set as made (some of it may have been touched since, by the
1909
+ // physics system's own audit earlier in the frame), and what its actors share
1910
+ // reads as it did (a model file edited is no fault of an actor's).
1911
+ function isAuditable(world, runtime, sprites, started, drops, was) {
1912
+ if (was.made !== runtime.stillActors?.made || world.generation !== started) return false;
1913
+ if (was.epoch !== was.epochNow || was.drops !== drops) return false;
1914
+ return sharedReadsTheSame(world, was, sprites, runtime.files);
1915
+ }
1916
+
1917
+ function isAsAdopted(world, runtime, sprites, started, drops, pass) {
1918
+ const keeper = world.stillKeeper;
1919
+ const still = keeper.adopted;
1920
+ if (!still || !keeper.alone(pass, runtime.stillVersion) || world.generation !== started || world.staticActorsOff === true) return false;
1921
+ if (still.epoch !== world.skipping.epoch || still.drops !== drops) return false;
1922
+ return sharedReadsTheSame(world, still, sprites, runtime.files);
1923
+ }
1924
+
1925
+ // Whether what the still actors share reads as it did when they were adopted:
1926
+ // each model file one of them places (its signature has the look switch in
1927
+ // it: `modelArtSignature`), each art one names.
1928
+ function sharedReadsTheSame(world, still, sprites, files) {
1929
+ if (!artReadsTheSame(still.arts, sprites)) return false;
1930
+ const placed = still.files;
1931
+ for (let i = 0; i < placed.length; i += 2) {
1932
+ if (modelSigOf(world, placed[i], sprites, files) !== placed[i + 1]) return false;
1933
+ }
1934
+ return true;
1935
+ }
1936
+
1937
+ // A settled pass: `skippingPass` for the actors that are not still.
1938
+ function settledPass(world, runtime, sprites, dt, started, drops, place) {
1939
+ const skipEmptyHints = skipEmptyGaitHints(world, runtime);
1940
+ const still = runtime.stillActors;
1941
+ const seen = new Set();
1942
+ let skipped = 0;
1943
+ for (const actor of runtime.getActors()) {
1944
+ const t = actor.components.Transform;
1945
+ if (!t) continue;
1946
+ if (world.generation === started && still.has(actor)) {
1947
+ skipped += 1;
1948
+ continue;
1949
+ }
1950
+ seen.add(actor.id);
1951
+ if (renderActorSleeps(world, actor)) continue;
1952
+ const entry = place(world, actor, t, sprites, runtime.files, started, drops);
1953
+ animateActor(world, entry, dt, actor, skipEmptyHints);
1954
+ }
1955
+ if (world.generation !== started || seen.size + skipped !== world.nodes.size) {
1956
+ // A still actor passed over is still the runtime's, and keeps its node.
1957
+ for (const actor of still) seen.add(actor.id);
1958
+ releaseUnseen(world, seen);
1959
+ }
1960
+ if (world.instances.size > 0) {
1961
+ leavingTheEngine(world);
1962
+ aimInstances(world.camera);
1963
+ for (const instances of world.instances.values()) drawInstances(instances, world.camera);
1964
+ }
1965
+ return true;
1966
+ }
1967
+
1968
+ // Adopts the runtime's still set as this world's: every still actor's node
1969
+ // has just been found, placed and vouched for by an ordinary pass that nothing
1970
+ // interrupted. Each node may freeze from its next unchanged walk on. A still
1971
+ // actor whose model moves inside itself (a walker, a part in motion) cannot be
1972
+ // left alone: it is touched, and the pass after that adopts the rest.
1973
+ function adoptStill(world, runtime, drops) {
1974
+ const set = runtime.keepsStaticActors === true && world.staticActorsOff !== true ? runtime.stillActors : null;
1975
+ if (!set || set.size === 0) return null;
1976
+ const found = stillNodes(world, set, drops);
1977
+ // Not every one vouched for by this pass: nothing is adopted until one is.
1978
+ if (!found) return null;
1979
+ if (found.moving.length > 0) {
1980
+ for (const actor of found.moving) runtime.touch(actor);
1981
+ return null;
1982
+ }
1983
+ // From here a node may freeze, until the epoch moves or any scene's still
1984
+ // set changes.
1985
+ world.skipping.clock = runtime.stillClock;
1986
+ world.skipping.clockAt = world.skipping.clock();
1987
+ // (A node built by a pass that was not skipping, and kept since, is a plain
1988
+ // Group: it has nothing to freeze with, and three.js walks it as ever.)
1989
+ for (const node of found.nodes) {
1990
+ if (node instanceof ActorNode) {
1991
+ freezeWhenUnchanged(node);
1992
+ if (world.emptyNodes) freezeEmptyNode(world, node);
1993
+ if (world.emptyPass) checkEmptyPass(world);
1994
+ }
1995
+ }
1996
+ return { made: set.made, epoch: world.skipping.epoch, count: found.nodes.length, drops, files: [...found.files].flat(), arts: found.arts, cursor: 0 };
1997
+ }
1998
+
1999
+ // The nodes of the still actors, the ones whose model moves inside itself,
2000
+ // and what the rest share: each model file placed with its signature, each
2001
+ // art named with what it read as. Null when any of them has no node this
2002
+ // pass vouched for.
2003
+ function stillNodes(world, set, drops) {
2004
+ const found = { nodes: [], moving: [], files: new Map(), arts: [] };
2005
+ const artsSeen = new Set();
2006
+ for (const actor of set) {
2007
+ if (!actor.components.Transform) continue;
2008
+ const entry = world.nodes.get(actor.id);
2009
+ const built = entry && world.snapshots.get(entry)?.builtFrom;
2010
+ if (!built || built.drops !== drops) return null;
2011
+ if (movesInside(world, entry)) {
2012
+ found.moving.push(actor);
2013
+ continue;
2014
+ }
2015
+ found.nodes.push(entry.node);
2016
+ const file = actor.components.Model?.file;
2017
+ if (file) found.files.set(file, built.modelSig);
2018
+ addArtReads(found.arts, artsSeen, built.artReads);
2019
+ }
2020
+ return found;
2021
+ }
2022
+
2023
+ // Whether the node's model walks or has parts in motion.
2024
+ function movesInside(world, entry) {
2025
+ const template = entry.modelKey ? world.models.get(entry.modelKey)?.template : null;
2026
+ return Boolean(template) && !isStaticModel(template);
2027
+ }
2028
+
2029
+ // Adds to `arts` the reads of `artReads` (`[path, art, ready, ...]`) whose
2030
+ // path it does not have yet.
2031
+ function addArtReads(arts, seen, artReads) {
2032
+ for (let i = 0; i < artReads.length; i += 3) {
2033
+ if (seen.has(artReads[i])) continue;
2034
+ seen.add(artReads[i]);
2035
+ arts.push(artReads[i], artReads[i + 1], artReads[i + 2]);
2036
+ }
2037
+ }
2038
+
2039
+ // `world.auditStatic`: what an ordinary pass would have found for a few still
2040
+ // actors. See the notes above.
2041
+ function auditStill(world, runtime, sprites, drops, was) {
2042
+ const still = world.stillKeeper.adopted ?? was;
2043
+ const actors = [...runtime.stillActors];
2044
+ const many = Math.min(world.auditStatic, actors.length);
2045
+ for (let k = 0; k < many; k++) {
2046
+ const actor = actors[(still.cursor + k) % actors.length];
2047
+ const what = whatChanged(world, runtime, actor, sprites, drops);
2048
+ if (!what) continue;
2049
+ // Touched first: the note warns on the console, which is not the engine's.
2050
+ runtime.touch(actor);
2051
+ noteChangedStill(world, actor.id, what);
2052
+ }
2053
+ still.cursor = (still.cursor + many) % Math.max(1, actors.length);
2054
+ }
2055
+
2056
+ // What about a still actor no longer reads as the last ordinary pass left it,
2057
+ // or null.
2058
+ function whatChanged(world, runtime, actor, sprites, drops) {
2059
+ const t = actor.components.Transform;
2060
+ const entry = world.nodes.get(actor.id);
2061
+ if (!t) return entry ? 'its Transform (removed)' : null;
2062
+ if (!entry) return 'its node (gone)';
2063
+ if (!looksTheSame(world, entry, actor, sprites, runtime.files, drops)) return 'a component its node is built from';
2064
+ const node = entry.node;
2065
+ if (!sameTurn(node.position, t.x, t.y, t.z)) return 'its Transform (where it is)';
2066
+ if (actor.runtime?.quat || !turnedAs(node, t, world.snapshots.get(entry)?.turnedTo)) return 'its Transform (how it is turned)';
2067
+ if (node.computedFrom && !subtreeIsAsRecorded(node)) return 'its node, or an object under it,';
2068
+ return null;
2069
+ }
2070
+
2071
+ // Whether `turnNode` would leave the node's rotation as it is.
2072
+ function turnedAs(node, t, was) {
2073
+ if (!was || node.rotation.order !== was.order || !sameQuaternion(node.quaternion, was)) return false;
2074
+ return sameTurn(node.rotation, t.rotationX * DEG, t.rotationY * DEG, t.rotationZ * DEG);
2075
+ }