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
@@ -7,6 +7,10 @@ import { systemInstallers } from './systemRegistry';
7
7
  import { deckFontFamily } from './fonts';
8
8
  import { wrapText } from './text';
9
9
  import { updateTaps } from './tap';
10
+ import { nextStillVersion, stillClock, StillKeeper } from './stillClock';
11
+ import { readSkyKey } from './skyKey';
12
+ import { actorUpdateDt } from './updateBudget';
13
+ import { FrozenActors, cloneFrozenData } from './frozenActors';
10
14
 
11
15
  const CARD_WIDTH = 500;
12
16
  const CARD_HEIGHT = 700;
@@ -128,6 +132,31 @@ function sceneDropsEmptyParts(data) {
128
132
  return data?.engine?.dropEmptyParts === true;
129
133
  }
130
134
 
135
+ // `"engine": { "staticActors": true }` at a scene file's top level, in a scene
136
+ // that also set `skipUnchangedActors`: the scene asks the engine not to visit,
137
+ // frame after frame, the actors its file marks `"static": true` (beside `id`
138
+ // and `components`), until something says one has changed (`scene.touch`). The
139
+ // 3d kit's CLAUDE.md has the terms. Off unless a scene says so with exactly
140
+ // `true`, and without the other key it does nothing.
141
+ function sceneKeepsStaticActors(data) {
142
+ return data?.engine?.staticActors === true && data?.engine?.skipUnchangedActors === true;
143
+ }
144
+
145
+ function sceneFreezesStatics(data) {
146
+ if (data?.engine?.frozenStatics !== true) return false;
147
+ if (sceneKeepsStaticActors(data)) return true;
148
+ console.warn('frozenStatics requires skipUnchangedActors and staticActors; ignoring frozenStatics');
149
+ return false;
150
+ }
151
+
152
+ // What a behaviour class does on its own, frame by frame or when switched on
153
+ // or off. An actor with a component of such a class is never still.
154
+ const ACTS = ['update', 'onEnable', 'onDisable'];
155
+
156
+ function actsOnItsOwn(Behavior) {
157
+ return ACTS.some((hook) => typeof Behavior?.prototype?.[hook] === 'function');
158
+ }
159
+
131
160
  // `"engine": { "camera": { "follow": "rigid" } }` at a scene file's top level:
132
161
  // the scene asks the 3d kit's Player for a follow camera that moves with the
133
162
  // player rather than easing after it (its CLAUDE.md has the terms). Off unless
@@ -145,6 +174,26 @@ function sceneCameraControl(data) {
145
174
  return sceneCameraFollowsRigidly(data) && data.engine.camera.control === 'orbit' ? 'orbit' : null;
146
175
  }
147
176
 
177
+ // `"engine": { "look": { "bake": "deferred" } }` at a scene file's top level:
178
+ // the scene asks the 3d kit to draw its models before their look's occlusion
179
+ // and outlines are baked, and to bake those over the frames that follow (its
180
+ // CLAUDE.md has the terms). Off unless a scene says so with exactly
181
+ // "deferred". Nothing in this kit reads it.
182
+ function sceneBakesLookLater(data) {
183
+ return data?.engine?.look?.bake === 'deferred';
184
+ }
185
+
186
+ // `"engine": { "maxFps": 60 }` at a scene file's top level: the scene asks the
187
+ // 3d kit's player to run its frame (behaviours, physics, drawing) no more
188
+ // often than that on a display that refreshes faster (its CLAUDE.md has the
189
+ // terms). 0, no cap, unless a scene says so with a finite number from 30 to
190
+ // 240 (below 30 a frame would be longer than physics can step). Nothing in
191
+ // this kit reads it.
192
+ function sceneMaxFps(data) {
193
+ const fps = data?.engine?.maxFps;
194
+ return typeof fps === 'number' && Number.isFinite(fps) && fps >= 30 && fps <= 240 ? fps : 0;
195
+ }
196
+
148
197
  // Whether a Layout's z is plain data: its own stored value, or absent
149
198
  // altogether. One that is computed when read (an accessor, or carried by a
150
199
  // prototype) is left to the sort, which reads it in the sort's own order.
@@ -205,6 +254,166 @@ export class SceneRuntime {
205
254
  return this.#dropsEmptyParts;
206
255
  }
207
256
 
257
+ // Play-only: the 3d kit keeps empty actor nodes outside its draw scene.
258
+ #skipsEmptyNodes = false;
259
+
260
+ get skipsEmptyNodes() {
261
+ return this.#skipsEmptyNodes;
262
+ }
263
+
264
+ // Whether the loaded scene asked for `engine.staticActors` (and for
265
+ // `skipUnchangedActors`, without which it is not on). Set by `load`, as
266
+ // `skipsUnchangedActors` is.
267
+ #keepsStatic = false;
268
+
269
+ get keepsStaticActors() {
270
+ return this.#keepsStatic;
271
+ }
272
+
273
+ #frozen = null;
274
+ #frozenUpdates = null;
275
+
276
+ get frozenActors() { return this.#frozen; }
277
+ get freezesStatics() { return this.#frozen !== null; }
278
+
279
+ // Capability, independent of scene keys. Older published runtimes have no
280
+ // fence; kits must check this marker before installing beforeBehavior.
281
+ get callsBeforeBehavior() { return true; }
282
+
283
+ // For a scene that asked: the actors that are still, or null for a scene
284
+ // that did not. An actor is still when its scene file marked it
285
+ // `"static": true`, it has no `Body`, none of its components' classes acts on
286
+ // its own (`actsOnItsOwn`), and nothing has touched it since the load. The
287
+ // engine leaves a still actor out of its per-frame loops. `stillVersion`
288
+ // is a number no other state of this set, or of any other runtime's, has:
289
+ // it moves whenever the set changes. What the engine keeps about the set is
290
+ // kept against that number, and a frame on which the number is new to it
291
+ // visits every actor, as before.
292
+ #still = null;
293
+ #stillVersion = 0;
294
+ // The ids touched since the load, which no later reckoning of the set (a
295
+ // change of behaviour classes) lets back in.
296
+ #touched = null;
297
+ // `update`'s own adoption of the still set (stillClock.js has the rule and
298
+ // the StillKeeper that is the whole of it). Made the first time a scene
299
+ // that asks is loaded.
300
+ #keeper = null;
301
+
302
+ get stillActors() {
303
+ return this.#still;
304
+ }
305
+
306
+ get stillVersion() {
307
+ return this.#stillVersion;
308
+ }
309
+
310
+ // A function that returns the last `stillVersion` handed to any runtime: it
311
+ // moves whenever any scene's still set changes (stillClock.js). Handed out
312
+ // here so that what reads it need not import this kit by path.
313
+ get stillClock() {
314
+ return stillClock;
315
+ }
316
+
317
+ // A keeper of its own for a system that leaves still actors out of a pass
318
+ // (stillClock.js): the 3d kit's world and its physics system each ask for
319
+ // one, here, so that they need not import this kit by path.
320
+ newStillKeeper() {
321
+ return new StillKeeper();
322
+ }
323
+
324
+ // Says an actor is being changed by something the engine does not watch: a
325
+ // component written, added or removed, its node posed. The actor is not
326
+ // still from here to the next load; it is visited every frame, and followed
327
+ // from the frame of the touch on. Costs nothing for an actor that is not
328
+ // still, and does nothing in a scene that did not ask for `staticActors`.
329
+ touch(actorOrId) {
330
+ if (this.#frozen) {
331
+ const actor = typeof actorOrId === 'string' ? this.actors.get(actorOrId) : actorOrId;
332
+ if (actor) this.#frozen.mark(actor);
333
+ return;
334
+ }
335
+ if (this.#still === null) return;
336
+ const actor = typeof actorOrId === 'string' ? this.actors.get(actorOrId) : actorOrId;
337
+ if (!actor) return;
338
+ this.#touched.add(actor.id);
339
+ if (this.#still.delete(actor)) this.#stillVersion = nextStillVersion();
340
+ }
341
+
342
+ // Touches every still actor at once: nothing is still from here to the next
343
+ // load. For a world that cannot leave actors alone (the 3d kit's scene
344
+ // editor, a world drawing copies of a model together).
345
+ releaseStill() {
346
+ if (this.#frozen) for (const actor of this.actors.values()) this.#frozen.release(actor);
347
+ if (this.#still === null || this.#still.size === 0) return;
348
+ for (const actor of this.#still) this.#touched.add(actor.id);
349
+ this.#noneStill();
350
+ }
351
+
352
+ // An empty still set under a new version: what stands while the set is
353
+ // being reckoned again, so that a reckoning that throws leaves no actor
354
+ // still rather than the ones that were.
355
+ #noneStill() {
356
+ this.#still = new Set();
357
+ this.#stillVersion = nextStillVersion();
358
+ this.#still.made = this.#stillVersion;
359
+ }
360
+
361
+ // The still set, reckoned from the scene's marks and the classes now
362
+ // registered. A new Set each time, so nothing kept against the old one is
363
+ // taken for this one.
364
+ #findStill() {
365
+ const still = new Set();
366
+ for (const actor of this.actors.values()) {
367
+ if (actor.static !== true || this.#touched.has(actor.id) || actor.components.Body) continue;
368
+ const names = Object.keys(actor.components);
369
+ if (names.some((name) => actsOnItsOwn(this.behaviors.get(name)))) continue;
370
+ still.add(actor);
371
+ }
372
+ this.#still = still;
373
+ this.#stillVersion = nextStillVersion();
374
+ // The version this Set was made at: the one number that stays with it
375
+ // while actors leave it.
376
+ still.made = this.#stillVersion;
377
+ }
378
+
379
+ // `update` for a scene that holds actors still: the same steps, with the
380
+ // still actors left out of the loop while this runtime has adopted its
381
+ // still set (stillClock.js). The whole update is one pass to the keeper: an
382
+ // ordinary one adopts only once the behaviours AND every system have run
383
+ // and returned, with no update entered from inside it and the still set
384
+ // unmoved; a throw anywhere in it, or an update inside it, leaves nothing
385
+ // adopted.
386
+ #updateHoldingStill(dt, frozenPass) {
387
+ const keeper = this.#keeper;
388
+ const pass = keeper.begin(this.#stillVersion);
389
+ let completed = false;
390
+ try {
391
+ this.time += dt;
392
+ updateTaps(this);
393
+ for (const actor of frozenPass ? frozenPass.take() : this.getActors()) {
394
+ // A still actor has no component that updates or is told of being
395
+ // switched on or off, and was run with the rest by the update that
396
+ // adopted. Once this update is no longer alone (a behaviour updated
397
+ // the scene from inside it) or the set has changed (one touched an
398
+ // actor, or loaded a scene), the rest of the loop runs every actor.
399
+ if (frozenPass) {
400
+ if (this.actors.get(actor.id) !== actor || this.isActorSleeping(actor)) continue;
401
+ } else if (pass.settled && keeper.alone(pass, this.#stillVersion) && this.#still.has(actor)) continue;
402
+ const actorDt = actorUpdateDt(actor, dt);
403
+ if (actorDt === null) continue;
404
+ this.#syncEnabled(actor);
405
+ this.forEachBehavior(actor, (instance) => instance.update?.(actor, this, actorDt));
406
+ }
407
+ for (const system of this.systems) {
408
+ system.afterBehaviors?.(this, dt);
409
+ }
410
+ this.reapPointers();
411
+ completed = true;
412
+ } finally {
413
+ keeper.end(pass, completed, this.#stillVersion, () => (this.#still !== null && this.#still.size > 0 ? {} : null));
414
+ }
415
+ }
416
+
208
417
  // Whether the loaded scene asked for `engine.camera.follow: "rigid"`. Set
209
418
  // by `load`, as `skipsUnchangedActors` is.
210
419
  #cameraFollowsRigidly = false;
@@ -221,6 +430,39 @@ export class SceneRuntime {
221
430
  return this.#cameraControl;
222
431
  }
223
432
 
433
+ // Whether the loaded scene asked for `engine.look.bake: "deferred"`. Set by
434
+ // `load`, as `skipsUnchangedActors` is.
435
+ #bakesLookLater = false;
436
+
437
+ get bakesLookLater() {
438
+ return this.#bakesLookLater;
439
+ }
440
+
441
+ // What the loaded scene asked for with `engine.sky` (skyKey.js), or null:
442
+ // for a scene with no such key, and for one whose key is malformed. Set by
443
+ // `load`, as `skipsUnchangedActors` is. The 3d kit draws it.
444
+ #sky = null;
445
+
446
+ get sky() {
447
+ return this.#sky;
448
+ }
449
+
450
+ // For a scene with `engine.sky`: the zone the player is in and the sky
451
+ // being drawn, to read -- `{ id, blend, from, to }` (skyKey.js). The same
452
+ // object from a load to the next; the 3d kit keeps it current as it draws.
453
+ // null for a scene without the key, where nothing works it out.
454
+ get skyZone() {
455
+ return this.#sky === null ? null : this.#sky.zone;
456
+ }
457
+
458
+ // The frame rate the loaded scene capped its play loop at with
459
+ // `engine.maxFps`, or 0. Set by `load`, as `skipsUnchangedActors` is.
460
+ #maxFps = 0;
461
+
462
+ get maxFps() {
463
+ return this.#maxFps;
464
+ }
465
+
224
466
  // `files` is the live deck files map (path -> text), used to resolve every
225
467
  // actor's `blueprint` ref against the CURRENT blueprint file content -- not
226
468
  // a load-time snapshot -- so a blueprint edit propagates to every scene that
@@ -274,6 +516,7 @@ export class SceneRuntime {
274
516
  // the difference that matters to a system holding something the browser keeps
275
517
  // doing on its own -- a playing sound outlives its scene otherwise.
276
518
  dispose() {
519
+ this.#frozen?.dispose();
277
520
  for (const system of this.systems) system.dispose?.(this);
278
521
  }
279
522
 
@@ -311,6 +554,9 @@ export class SceneRuntime {
311
554
  // (`setBehaviors` doesn't touch the cache directly; a stale entry is simply
312
555
  // caught here on next access).
313
556
  #instanceFor(actor, name, Behavior, props) {
557
+ // Optional kit fence before constructors or any consumer callback. It
558
+ // also covers collisions, taps, enabled transitions and direct behavior().
559
+ this.beforeBehavior?.(actor, name);
314
560
  const cache = (actor.runtime.$behaviors ??= new Map());
315
561
  const cached = cache.get(name);
316
562
  if (cached && cached.constructor === Behavior) return cached;
@@ -334,6 +580,8 @@ export class SceneRuntime {
334
580
  // `.constructor !== Behavior` is caught lazily by `#instanceFor` on next
335
581
  // access, so `this.state` survives a hot swap.
336
582
  setBehaviors(classes) {
583
+ // No actor is still while the classes change under them.
584
+ if (this.#still !== null) this.#noneStill();
337
585
  this.behaviors = behaviorMapFrom(classes);
338
586
  for (const actor of this.actors.values()) {
339
587
  for (const [name, Behavior] of this.behaviors) {
@@ -344,20 +592,75 @@ export class SceneRuntime {
344
592
  }
345
593
  }
346
594
  }
595
+ // A class may have gained or lost an `update`.
596
+ if (this.#still !== null) this.#findStill();
597
+ this.#frozen?.markAll();
598
+ }
599
+
600
+ // Lazily allocated by a kit that streams a scene. Sleeping actors retain
601
+ // ID lookup, components, behavior state and serialization; live passes only
602
+ // visit awake actors. Spawns wake their ID and loads discard the sleep set.
603
+ #awakeActors = null;
604
+ #sleepingActors = null;
605
+
606
+ setActorSleeping(actorOrId, sleeping) {
607
+ const actor = typeof actorOrId === 'string' ? this.actors.get(actorOrId) : actorOrId;
608
+ if (!actor || this.actors.get(actor.id) !== actor) return false;
609
+ this.#frozen?.mark(actor);
610
+ if (!sleeping && !this.#awakeActors) return true;
611
+ this.#awakeActors ??= new Map(this.actors);
612
+ this.#sleepingActors ??= new Set();
613
+ if (sleeping) {
614
+ this.touch(actor);
615
+ this.#awakeActors.delete(actor.id);
616
+ this.#sleepingActors.add(actor.id);
617
+ } else {
618
+ this.#sleepingActors.delete(actor.id);
619
+ this.#awakeActors.set(actor.id, actor);
620
+ if (!this.#sleepingActors.size) {
621
+ this.#awakeActors = null;
622
+ this.#sleepingActors = null;
623
+ }
624
+ }
625
+ return true;
347
626
  }
348
627
 
628
+ isActorSleeping(actor) { return this.#sleepingActors?.has(actor.id) === true; }
629
+
349
630
  load(sceneData) {
631
+ if (this.#frozen) sceneData = cloneFrozenData(sceneData);
632
+ this.#frozen?.dispose();
633
+ this.#frozen = null;
634
+ this.#frozenUpdates = null;
635
+ // No actor of the scene being left is still from here on, whether or not
636
+ // the load completes.
637
+ if (this.#still !== null) {
638
+ this.#still = null;
639
+ this.#touched = null;
640
+ this.#stillVersion = nextStillVersion();
641
+ this.#keeper.interrupt();
642
+ }
350
643
  // Reset registered systems (e.g. physics) so a reload/restart/scene
351
644
  // transition starts from the authored layout -- otherwise a system holding
352
645
  // simulation state (body positions, joints) would carry it across the load.
353
646
  // No-op on the constructor's first load, before any system is registered.
354
647
  for (const system of this.systems) system.reset?.(this);
648
+ this.#awakeActors = null;
649
+ this.#sleepingActors = null;
355
650
  this.data = structuredClone(sceneData);
356
651
  this.#skipUnchanged = sceneSkipsUnchangedActors(this.data);
357
652
  this.#nearShadowDistance = sceneNearShadowDistance(this.data);
358
653
  this.#dropsEmptyParts = sceneDropsEmptyParts(this.data);
654
+ this.#skipsEmptyNodes = this.data?.engine?.skipEmptyNodes === true;
655
+ this.#keepsStatic = sceneKeepsStaticActors(this.data);
359
656
  this.#cameraFollowsRigidly = sceneCameraFollowsRigidly(this.data);
360
657
  this.#cameraControl = sceneCameraControl(this.data);
658
+ // Orbit extras must be available before any code in the new scene runs.
659
+ // Keep registrations across loads, and allocate nothing for keyless worlds.
660
+ if (this.#cameraControl === 'orbit' && this.three) this.three.ownModelWith ??= new Set();
661
+ this.#bakesLookLater = sceneBakesLookLater(this.data);
662
+ this.#sky = readSkyKey(this.data);
663
+ this.#maxFps = sceneMaxFps(this.data);
361
664
  this.actors = new Map();
362
665
  for (const actor of this.data.actors ?? []) {
363
666
  this.#initActor(actor);
@@ -376,6 +679,15 @@ export class SceneRuntime {
376
679
  }
377
680
  }
378
681
  }
682
+ if (this.#keepsStatic) {
683
+ this.#keeper ??= new StillKeeper();
684
+ this.#touched = new Set();
685
+ this.#findStill();
686
+ }
687
+ if (sceneFreezesStatics(this.data)) {
688
+ this.#frozen = new FrozenActors(this);
689
+ for (const actor of this.actors.values()) this.#frozen.add(actor);
690
+ }
379
691
  }
380
692
 
381
693
  // Read and parse a scene file by name, returning its scene data. Use this
@@ -432,6 +744,7 @@ export class SceneRuntime {
432
744
  }
433
745
 
434
746
  serialize() {
747
+ if (this.#frozen) return cloneFrozenData(this.data);
435
748
  return structuredClone(this.data);
436
749
  }
437
750
 
@@ -448,7 +761,7 @@ export class SceneRuntime {
448
761
 
449
762
  getActors() {
450
763
  if (this.#skipUnchanged) return this.#actorsSkippingSort();
451
- return [...this.actors.values()].sort((a, b) => {
764
+ return [...(this.#awakeActors ?? this.actors).values()].sort((a, b) => {
452
765
  const az = getLayout(a)?.z ?? 0;
453
766
  const bz = getLayout(b)?.z ?? 0;
454
767
  return az - bz;
@@ -458,7 +771,7 @@ export class SceneRuntime {
458
771
  // `getActors` for a scene that set `skipUnchangedActors`: the same list,
459
772
  // sorted only when it is not already in order.
460
773
  #actorsSkippingSort() {
461
- const actors = [...this.actors.values()];
774
+ const actors = [...(this.#awakeActors ?? this.actors).values()];
462
775
  if (alreadyInLayoutOrder(actors)) return actors;
463
776
  return actors.sort((a, b) => (getLayout(a)?.z ?? 0) - (getLayout(b)?.z ?? 0));
464
777
  }
@@ -516,9 +829,15 @@ export class SceneRuntime {
516
829
  components[name] = Behavior ? { ...Behavior.defaultProps, ...props } : { ...props };
517
830
  }
518
831
  const next = { ...actor, id, components };
832
+ // Only an actor of the scene's file can be still, whatever a spawned one's
833
+ // own data says.
834
+ if (this.#touched !== null) this.#touched.add(id);
519
835
  this.#initActor(next);
520
836
  this.data.actors.push(next);
521
837
  this.actors.set(id, next);
838
+ this.#sleepingActors?.delete(id);
839
+ this.#awakeActors?.set(id, next);
840
+ this.#frozen?.add(next, true);
522
841
  return next;
523
842
  }
524
843
 
@@ -535,7 +854,11 @@ export class SceneRuntime {
535
854
  despawnActor(actorId) {
536
855
  const actor = this.actors.get(actorId);
537
856
  if (!actor) return false;
857
+ this.#frozen?.remove(actor);
858
+ if (this.#still !== null && this.#still.delete(actor)) this.#stillVersion = nextStillVersion();
538
859
  this.actors.delete(actorId);
860
+ this.#sleepingActors?.delete(actorId);
861
+ this.#awakeActors?.delete(actorId);
539
862
  const idx = this.data.actors.findIndex((a) => a.id === actorId);
540
863
  if (idx !== -1) this.data.actors.splice(idx, 1);
541
864
  return true;
@@ -683,13 +1006,24 @@ export class SceneRuntime {
683
1006
  }
684
1007
 
685
1008
  update(dt) {
1009
+ if (this.#frozen) {
1010
+ this.#updateHoldingStill(dt, this.#frozenUpdates ??= this.#frozen.consumer());
1011
+ return;
1012
+ }
1013
+ // A scene that holds actors still (`"engine": { "staticActors": true }`).
1014
+ if (this.#still !== null) {
1015
+ this.#updateHoldingStill(dt);
1016
+ return;
1017
+ }
686
1018
  this.time += dt;
687
1019
  // Before controls, so a tap on an actor that implements `onTap` claims the
688
1020
  // finger first. Targeted controls (Draggable) can still take it afterward.
689
1021
  updateTaps(this);
690
1022
  for (const actor of this.getActors()) {
1023
+ const actorDt = actorUpdateDt(actor, dt);
1024
+ if (actorDt === null) continue;
691
1025
  this.#syncEnabled(actor);
692
- this.forEachBehavior(actor, (instance) => instance.update?.(actor, this, dt));
1026
+ this.forEachBehavior(actor, (instance) => instance.update?.(actor, this, actorDt));
693
1027
  }
694
1028
  // Behaviors have expressed their intent (velocities, forces) for this frame;
695
1029
  // now let registered systems advance (e.g. physics integrates, writes results
@@ -0,0 +1,129 @@
1
+ // `"engine": { "sky": { ... } }` at a scene file's top level: the scene asks
2
+ // the 3d kit to draw a sky behind everything, the sky of the zone the player
3
+ // stands in (its CLAUDE.md has the terms). This file reads the key; nothing
4
+ // in this kit draws it.
5
+ //
6
+ // "sky": {
7
+ // "fade": 1.5, // optional: seconds one zone's sky takes to turn into another's; above 0, at most 10
8
+ // "edge": 0.75, // optional: metres past a zone's box a player is still in it; 0 to 10
9
+ // "below": 8, // optional: degrees under the horizon an image's last row is; 0 to 45
10
+ // "zones": [ // 1 to 16
11
+ // { "id": "square", "color": "#bfe3f2", "art": "drawings/sky-square.webp" },
12
+ // { "id": "hollow", "color": "#3d3a5c", "art": "drawings/sky-hollow.webp", "box": [-95, -17, -17, 17] }
13
+ // ]
14
+ // }
15
+ //
16
+ // A zone is `id` (a string, not empty, not another zone's), `color`
17
+ // (`#rrggbb`: the sky where the zone has no image, or its image has not
18
+ // arrived or failed), optionally `art` (a deck image's path) and optionally
19
+ // `box` (`[x0, z0, x1, z1]`, metres, x0 < x1 and z0 < z1). Exactly one zone
20
+ // has no box: the sky of a point in no box. A point in two boxes is in the
21
+ // one listed first.
22
+ //
23
+ // The shape is exact. Anything else -- a key this file does not name, a
24
+ // number out of its range, a colour that is not six hex digits, two zones
25
+ // with one id, no zone without a box or two -- and the scene has no sky: the
26
+ // key reads as absent, with one warning that says what was wrong.
27
+ //
28
+ // No imports: the 3d kit's tests load it alone.
29
+
30
+ const SKY_KEYS = new Set(['fade', 'edge', 'below', 'zones']);
31
+ const ZONE_KEYS = new Set(['id', 'color', 'art', 'box']);
32
+ export const SKY_FADE = 1.5;
33
+ export const SKY_EDGE = 0.75;
34
+ export const SKY_BELOW = 8;
35
+ const MOST_ZONES = 16;
36
+
37
+ const isPlain = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
38
+ const within = (value, least, most) => typeof value === 'number' && Number.isFinite(value) && value >= least && value <= most;
39
+
40
+ // What is wrong with a zone, or null.
41
+ function zoneFault(zone, seen) {
42
+ if (!isPlain(zone)) return 'a zone is not an object';
43
+ for (const key of Object.keys(zone)) if (!ZONE_KEYS.has(key)) return `a zone has "${key}"`;
44
+ if (typeof zone.id !== 'string' || zone.id === '') return 'a zone has no id';
45
+ if (seen.has(zone.id)) return `two zones are "${zone.id}"`;
46
+ if (typeof zone.color !== 'string' || !/^#[0-9a-fA-F]{6}$/.test(zone.color)) return `zone "${zone.id}" has no #rrggbb color`;
47
+ if (zone.art !== undefined && (typeof zone.art !== 'string' || zone.art === '')) return `zone "${zone.id}" has an art that is not a path`;
48
+ if (zone.box !== undefined) {
49
+ const box = zone.box;
50
+ if (!Array.isArray(box) || box.length !== 4 || !box.every((n) => typeof n === 'number' && Number.isFinite(n))) {
51
+ return `zone "${zone.id}" has a box that is not four numbers`;
52
+ }
53
+ if (!(box[0] < box[2] && box[1] < box[3])) return `zone "${zone.id}" has a box that is not [x0, z0, x1, z1] with x0 < x1 and z0 < z1`;
54
+ }
55
+ return null;
56
+ }
57
+
58
+ // What is wrong with the key, or null.
59
+ function skyFault(sky) {
60
+ if (!isPlain(sky)) return 'it is not an object';
61
+ for (const key of Object.keys(sky)) if (!SKY_KEYS.has(key)) return `it has "${key}"`;
62
+ if (sky.fade !== undefined && !(within(sky.fade, 0, 10) && sky.fade > 0)) return '"fade" is not a number above 0 and at most 10';
63
+ if (sky.edge !== undefined && !within(sky.edge, 0, 10)) return '"edge" is not a number from 0 to 10';
64
+ if (sky.below !== undefined && !within(sky.below, 0, 45)) return '"below" is not a number from 0 to 45';
65
+ if (!Array.isArray(sky.zones) || sky.zones.length < 1 || sky.zones.length > MOST_ZONES) return `"zones" is not a list of 1 to ${MOST_ZONES}`;
66
+ const seen = new Set();
67
+ let open = 0;
68
+ for (const zone of sky.zones) {
69
+ const fault = zoneFault(zone, seen);
70
+ if (fault) return fault;
71
+ seen.add(zone.id);
72
+ if (zone.box === undefined) open += 1;
73
+ }
74
+ if (open !== 1) return `${open} zones have no box (exactly one must)`;
75
+ return null;
76
+ }
77
+
78
+ // The scene's sky as the 3d kit draws it, or null: for a scene with no
79
+ // `engine.sky` (the one read below and nothing else), and for a malformed one
80
+ // (with a warning). Made once a load and never changed, but for `state`,
81
+ // which the 3d kit writes as it draws and `zone` hands out to read:
82
+ //
83
+ // zone: { id, blend, from, to }
84
+ //
85
+ // `id` is the zone the player is in; the sky drawn is `from`'s turning into
86
+ // `to`'s, `blend` of the way there (0 to 1; at rest `from` and `to` are both
87
+ // `id` and `blend` is 0). Before a frame is drawn it is the zone with no box.
88
+ export function readSkyKey(data, warn = (message) => console.warn(message)) {
89
+ const sky = data?.engine?.sky;
90
+ if (sky === undefined) return null;
91
+ const fault = skyFault(sky);
92
+ if (fault) {
93
+ warn(`engine.sky is ignored: ${fault}.`);
94
+ return null;
95
+ }
96
+ const zones = sky.zones.map((zone) =>
97
+ Object.freeze({
98
+ id: zone.id,
99
+ color: zone.color.toLowerCase(),
100
+ art: zone.art ?? null,
101
+ box: zone.box ? Object.freeze([...zone.box]) : null,
102
+ })
103
+ );
104
+ const home = zones.findIndex((zone) => zone.box === null);
105
+ const state = { id: zones[home].id, blend: 0, from: zones[home].id, to: zones[home].id };
106
+ const zone = Object.freeze({
107
+ get id() {
108
+ return state.id;
109
+ },
110
+ get blend() {
111
+ return state.blend;
112
+ },
113
+ get from() {
114
+ return state.from;
115
+ },
116
+ get to() {
117
+ return state.to;
118
+ },
119
+ });
120
+ return Object.freeze({
121
+ fade: sky.fade ?? SKY_FADE,
122
+ edge: sky.edge ?? SKY_EDGE,
123
+ below: sky.below ?? SKY_BELOW,
124
+ zones: Object.freeze(zones),
125
+ home,
126
+ state,
127
+ zone,
128
+ });
129
+ }