castle-web-cli 0.4.232 → 0.4.233

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (355) hide show
  1. package/dist/agent-failures.d.ts +8 -0
  2. package/dist/agent-failures.js +19 -2
  3. package/dist/agent-prompts.d.ts +1 -1
  4. package/dist/agent-prompts.js +10 -3
  5. package/dist/agent.d.ts +64 -3
  6. package/dist/agent.js +170 -81
  7. package/dist/castle-host/host.d.ts +1 -0
  8. package/dist/castle-host/host.js +51 -3
  9. package/dist/castleJson.d.ts +4 -2
  10. package/dist/castleJson.js +2 -0
  11. package/dist/check.d.ts +3 -1
  12. package/dist/check.js +11 -1
  13. package/dist/devSessionStorage.js +47 -1
  14. package/dist/importPinMismatch.d.ts +22 -0
  15. package/dist/importPinMismatch.js +77 -0
  16. package/dist/importRegression.js +3 -15
  17. package/dist/imports.d.ts +10 -3
  18. package/dist/imports.js +88 -20
  19. package/dist/index.js +5 -4
  20. package/dist/init.js +1 -1
  21. package/dist/platformDoc.js +22 -0
  22. package/dist/routerFences.d.ts +5 -0
  23. package/dist/routerFences.js +12 -2
  24. package/dist/save-deck.d.ts +5 -0
  25. package/dist/save-deck.js +37 -4
  26. package/dist/serve.js +3 -0
  27. package/dist/shell/assets/{index-D2tWM896.js → index-BjOxR-lW.js} +4 -4
  28. package/dist/shell/assets/index-MVLfNYd9.css +1 -0
  29. package/dist/shell/index.html +2 -2
  30. package/dist/taskSteer.d.ts +13 -0
  31. package/dist/taskSteer.js +22 -2
  32. package/kits/base/castle.json +1 -1
  33. package/kits/base/package-lock.json +1 -1
  34. package/kits/base/sdk/README.md +79 -2
  35. package/kits/base/sdk/avatar.d.ts +6 -2
  36. package/kits/base/sdk/avatar.js +12 -4
  37. package/kits/base/sdk/castle.d.ts +1 -1
  38. package/kits/base/sdk/commands.d.ts +14 -0
  39. package/kits/base/sdk/hub.d.ts +6 -2
  40. package/kits/base/sdk/hub.js +13 -0
  41. package/kits/base/sdk/multiplayer.js +17 -1
  42. package/kits/base/sdk/save.js +2 -1
  43. package/kits/base/sdk/server/hub.d.ts +87 -0
  44. package/kits/base/sdk/server/hub.js +70 -0
  45. package/kits/base/sdk/server/platformHandle.d.ts +31 -1
  46. package/kits/base/sdk/server/storage.d.ts +13 -0
  47. package/kits/base/sdk/server/storage.js +46 -0
  48. package/kits/base/sdk/server/wrapper.d.ts +36 -5
  49. package/kits/base/sdk/server/wrapper.js +83 -8
  50. package/kits/hub-game/CLAUDE.md +329 -11
  51. package/kits/hub-game/blueprints/avatar-10.scene +28 -0
  52. package/kits/hub-game/blueprints/avatar-11.scene +28 -0
  53. package/kits/hub-game/blueprints/avatar-12.scene +28 -0
  54. package/kits/hub-game/blueprints/avatar-13.scene +28 -0
  55. package/kits/hub-game/blueprints/avatar-14.scene +28 -0
  56. package/kits/hub-game/blueprints/avatar-15.scene +28 -0
  57. package/kits/hub-game/blueprints/avatar-4.scene +28 -0
  58. package/kits/hub-game/blueprints/avatar-5.scene +28 -0
  59. package/kits/hub-game/blueprints/avatar-6.scene +28 -0
  60. package/kits/hub-game/blueprints/avatar-7.scene +28 -0
  61. package/kits/hub-game/blueprints/avatar-8.scene +28 -0
  62. package/kits/hub-game/blueprints/avatar-9.scene +28 -0
  63. package/kits/hub-game/code/client/actorBudget.js +47 -0
  64. package/kits/hub-game/code/client/attention.js +11 -2
  65. package/kits/hub-game/code/client/avatar.js +309 -35
  66. package/kits/hub-game/code/client/avatarCap.js +228 -0
  67. package/kits/hub-game/code/client/avatarColors.js +70 -0
  68. package/kits/hub-game/code/client/avatarFaces.js +21 -0
  69. package/kits/hub-game/code/client/avatarShare.js +251 -0
  70. package/kits/hub-game/code/client/ballot.js +467 -0
  71. package/kits/hub-game/code/client/build.js +22 -0
  72. package/kits/hub-game/code/client/chrome.js +1144 -50
  73. package/kits/hub-game/code/client/companion.js +716 -0
  74. package/kits/hub-game/code/client/companionDress.js +99 -0
  75. package/kits/hub-game/code/client/decor.js +509 -0
  76. package/kits/hub-game/code/client/earned.js +131 -0
  77. package/kits/hub-game/code/client/emoteBubble.js +75 -0
  78. package/kits/hub-game/code/client/grab.js +339 -20
  79. package/kits/hub-game/code/client/hookLayer.js +299 -13
  80. package/kits/hub-game/code/client/idle.js +163 -22
  81. package/kits/hub-game/code/client/interestCap.js +81 -0
  82. package/kits/hub-game/code/client/keys.js +36 -0
  83. package/kits/hub-game/code/client/labelsNear.js +205 -0
  84. package/kits/hub-game/code/client/menuIcons.js +34 -0
  85. package/kits/hub-game/code/client/pack.js +6 -2
  86. package/kits/hub-game/code/client/packFormat.js +3 -3
  87. package/kits/hub-game/code/client/rehello.js +167 -0
  88. package/kits/hub-game/code/client/shot.js +92 -0
  89. package/kits/hub-game/code/client/sound.js +63 -8
  90. package/kits/hub-game/code/client/soundscape.js +1151 -0
  91. package/kits/hub-game/code/client/soundscapeActions.js +99 -0
  92. package/kits/hub-game/code/client/soundscapeAmbience.js +453 -0
  93. package/kits/hub-game/code/client/soundscapeBaked.js +143 -0
  94. package/kits/hub-game/code/client/soundscapeBusker.js +217 -0
  95. package/kits/hub-game/code/client/soundscapeCourt.js +200 -0
  96. package/kits/hub-game/code/client/soundscapeCrowd.js +331 -0
  97. package/kits/hub-game/code/client/soundscapeCues.js +362 -0
  98. package/kits/hub-game/code/client/soundscapeMap.js +181 -0
  99. package/kits/hub-game/code/client/soundscapeMarket.js +176 -0
  100. package/kits/hub-game/code/client/soundscapeMusic.js +126 -0
  101. package/kits/hub-game/code/client/soundscapeMusicEngine.js +460 -0
  102. package/kits/hub-game/code/client/soundscapeSimlish.js +737 -0
  103. package/kits/hub-game/code/client/soundscapeSongs.js +127 -0
  104. package/kits/hub-game/code/client/soundscapeSongsRound3.js +63 -0
  105. package/kits/hub-game/code/client/soundscapeSynthesis.js +168 -0
  106. package/kits/hub-game/code/client/soundscapeUi.js +211 -0
  107. package/kits/hub-game/code/client/soundscapeVoice.js +1209 -0
  108. package/kits/hub-game/code/client/soundscapeWaves.js +206 -0
  109. package/kits/hub-game/code/client/spin.js +101 -0
  110. package/kits/hub-game/code/client/state.js +109 -1
  111. package/kits/hub-game/code/client/stuck.js +259 -0
  112. package/kits/hub-game/code/client/talk.js +538 -47
  113. package/kits/hub-game/code/client/tiers.js +516 -27
  114. package/kits/hub-game/code/client/toastBand.js +37 -0
  115. package/kits/hub-game/code/client/together.js +32 -0
  116. package/kits/hub-game/code/client/visibility.js +43 -0
  117. package/kits/hub-game/code/client/wear.js +461 -170
  118. package/kits/hub-game/code/client/yours.js +199 -0
  119. package/kits/hub-game/code/companionSpec.js +45 -0
  120. package/kits/hub-game/code/privateText.js +7 -0
  121. package/kits/hub-game/code/server/actions.js +133 -0
  122. package/kits/hub-game/code/server/actors.js +9 -1
  123. package/kits/hub-game/code/server/ask.js +155 -0
  124. package/kits/hub-game/code/server/ballot.js +539 -0
  125. package/kits/hub-game/code/server/cells.js +100 -0
  126. package/kits/hub-game/code/server/companion.js +82 -0
  127. package/kits/hub-game/code/server/cues.js +70 -0
  128. package/kits/hub-game/code/server/decor.js +269 -0
  129. package/kits/hub-game/code/server/earned.js +461 -0
  130. package/kits/hub-game/code/server/friendBests.js +166 -0
  131. package/kits/hub-game/code/server/friendsAmong.js +232 -0
  132. package/kits/hub-game/code/server/history.js +5 -0
  133. package/kits/hub-game/code/server/hub.js +1254 -50
  134. package/kits/hub-game/code/server/idle.js +30 -11
  135. package/kits/hub-game/code/server/index.js +2 -2
  136. package/kits/hub-game/code/server/labels.js +28 -2
  137. package/kits/hub-game/code/server/manifest.js +378 -7
  138. package/kits/hub-game/code/server/menu.js +133 -0
  139. package/kits/hub-game/code/server/npcs.js +830 -80
  140. package/kits/hub-game/code/server/party.js +2 -2
  141. package/kits/hub-game/code/server/players.js +22 -0
  142. package/kits/hub-game/code/server/shot.js +110 -0
  143. package/kits/hub-game/code/server/standing.js +124 -0
  144. package/kits/hub-game/code/server/vis.js +113 -0
  145. package/kits/hub-game/code/server/wear.js +12 -0
  146. package/kits/hub-game/code/server/yours.js +59 -0
  147. package/kits/hub-game/code/shared/cues.js +9 -0
  148. package/kits/hub-game/code/shared/decor.js +41 -0
  149. package/kits/hub-game/code/shared/shot.js +19 -0
  150. package/kits/hub-game/code/shared/spin.js +57 -0
  151. package/kits/hub-game/code/systems/hub.js +845 -95
  152. package/kits/hub-game/docs/content-pack.md +1 -1
  153. package/kits/hub-game/docs/contract.md +2244 -61
  154. package/kits/hub-game/docs/home-pieces.md +64 -0
  155. package/kits/hub-game/models/avatar-10.pxmodel +28 -0
  156. package/kits/hub-game/models/avatar-11.pxmodel +28 -0
  157. package/kits/hub-game/models/avatar-12.pxmodel +27 -0
  158. package/kits/hub-game/models/avatar-13.pxmodel +24 -0
  159. package/kits/hub-game/models/avatar-14.pxmodel +29 -0
  160. package/kits/hub-game/models/avatar-15.pxmodel +24 -0
  161. package/kits/hub-game/models/avatar-4.pxmodel +29 -0
  162. package/kits/hub-game/models/avatar-5.pxmodel +27 -0
  163. package/kits/hub-game/models/avatar-6.pxmodel +26 -0
  164. package/kits/hub-game/models/avatar-7.pxmodel +25 -0
  165. package/kits/hub-game/models/avatar-8.pxmodel +24 -0
  166. package/kits/hub-game/models/avatar-9.pxmodel +30 -0
  167. package/kits/hub-game/models/earned/badge-round.pxmodel +100 -0
  168. package/kits/hub-game/models/earned/badge-shield.pxmodel +117 -0
  169. package/kits/hub-game/models/earned/badge-star.pxmodel +87 -0
  170. package/kits/hub-game/models/earned/belt-plain.pxmodel +72 -0
  171. package/kits/hub-game/models/earned/held-ball.pxmodel +43 -0
  172. package/kits/hub-game/models/earned/held-lantern.pxmodel +85 -0
  173. package/kits/hub-game/models/earned/held-net.pxmodel +57 -0
  174. package/kits/hub-game/models/earned/held-trophy.pxmodel +109 -0
  175. package/kits/hub-game/models/earned/pin-round.pxmodel +62 -0
  176. package/kits/hub-game/models/earned/sash-plain.pxmodel +66 -0
  177. package/kits/hub-game/models/earned/square/belt-plain.pxmodel +104 -0
  178. package/kits/hub-game/models/earned/square/sash-plain.pxmodel +98 -0
  179. package/kits/hub-game/models/hats/bat-clip.pxmodel +206 -0
  180. package/kits/hub-game/models/hats/beekeeper.pxmodel +149 -0
  181. package/kits/hub-game/models/hats/cap.pxmodel +162 -0
  182. package/kits/hub-game/models/hats/captain.pxmodel +178 -0
  183. package/kits/hub-game/models/hats/crooked-top.pxmodel +172 -0
  184. package/kits/hub-game/models/hats/flower-crown.pxmodel +451 -0
  185. package/kits/hub-game/models/hats/foam-crown.pxmodel +179 -0
  186. package/kits/hub-game/models/hats/lantern.pxmodel +230 -0
  187. package/kits/hub-game/models/hats/laurel.pxmodel +533 -0
  188. package/kits/hub-game/models/hats/lighthouse.pxmodel +96 -0
  189. package/kits/hub-game/models/hats/sailor.pxmodel +141 -0
  190. package/kits/hub-game/models/hats/souwester.pxmodel +131 -0
  191. package/kits/hub-game/models/hats/straw.pxmodel +139 -0
  192. package/kits/hub-game/models/hats/sunflower.pxmodel +406 -0
  193. package/kits/hub-game/models/hats/sweatband.pxmodel +112 -0
  194. package/kits/hub-game/models/hats/witch.pxmodel +147 -0
  195. package/kits/hub-game/package-lock.json +2 -0
  196. package/kits/hub-game/package.json +2 -1
  197. package/kits/hub-game/scripts/check.mjs +78 -11
  198. package/kits/hub-game/scripts/companion-follower-wire.json +1 -0
  199. package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +121 -0
  200. package/kits/hub-game/scripts/fixtures/decor-keyless.json +293 -0
  201. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +23 -0
  202. package/kits/hub-game/scripts/fixtures/fake-dom.mjs +107 -0
  203. package/kits/hub-game/scripts/fixtures/interest-legacy.json +385 -0
  204. package/kits/hub-game/scripts/fixtures/npc-notes-v1.77.jsonl +4 -0
  205. package/kits/hub-game/scripts/fixtures/vis-shared-wire.json +1 -0
  206. package/kits/hub-game/scripts/gen-avatars.mjs +933 -16
  207. package/kits/hub-game/scripts/gen-earned.mjs +285 -0
  208. package/kits/hub-game/scripts/gen-hats.mjs +827 -0
  209. package/kits/hub-game/scripts/grab.before-orbit.mjs +400 -0
  210. package/kits/hub-game/scripts/soundscape-wave-analysis.mjs +125 -0
  211. package/kits/hub-game/scripts/test-actions-client.mjs +488 -0
  212. package/kits/hub-game/scripts/test-actions.mjs +298 -0
  213. package/kits/hub-game/scripts/test-actor-budget.mjs +44 -0
  214. package/kits/hub-game/scripts/test-actors.mjs +19 -17
  215. package/kits/hub-game/scripts/test-ask-client.mjs +358 -0
  216. package/kits/hub-game/scripts/test-ask.mjs +269 -0
  217. package/kits/hub-game/scripts/test-attention.mjs +10 -1
  218. package/kits/hub-game/scripts/test-avatar-cap.mjs +379 -0
  219. package/kits/hub-game/scripts/test-avatar-colors.mjs +72 -0
  220. package/kits/hub-game/scripts/test-avatar-models.mjs +181 -0
  221. package/kits/hub-game/scripts/test-avatar-share.mjs +318 -0
  222. package/kits/hub-game/scripts/test-avatar-wire.mjs +753 -0
  223. package/kits/hub-game/scripts/test-avatar.mjs +540 -7
  224. package/kits/hub-game/scripts/test-ballot.mjs +1001 -0
  225. package/kits/hub-game/scripts/test-build.mjs +31 -0
  226. package/kits/hub-game/scripts/test-cells.mjs +71 -0
  227. package/kits/hub-game/scripts/test-chat.mjs +662 -0
  228. package/kits/hub-game/scripts/test-classic.mjs +2 -0
  229. package/kits/hub-game/scripts/test-companion-chat.mjs +198 -0
  230. package/kits/hub-game/scripts/test-companion-client.mjs +1167 -0
  231. package/kits/hub-game/scripts/test-companion.mjs +259 -0
  232. package/kits/hub-game/scripts/test-decor-client.mjs +303 -0
  233. package/kits/hub-game/scripts/test-decor.mjs +457 -0
  234. package/kits/hub-game/scripts/test-earned-client.mjs +459 -0
  235. package/kits/hub-game/scripts/test-earned.mjs +1194 -0
  236. package/kits/hub-game/scripts/test-emote-bubble.mjs +110 -0
  237. package/kits/hub-game/scripts/test-friend-bests.mjs +435 -0
  238. package/kits/hub-game/scripts/test-grab-orbit.mjs +918 -0
  239. package/kits/hub-game/scripts/test-grab.mjs +7 -0
  240. package/kits/hub-game/scripts/test-hats.mjs +422 -168
  241. package/kits/hub-game/scripts/test-hub-leaving.mjs +203 -0
  242. package/kits/hub-game/scripts/test-hub-ops.mjs +439 -2
  243. package/kits/hub-game/scripts/test-hub-trip.mjs +716 -2
  244. package/kits/hub-game/scripts/test-hud-clear.mjs +328 -4
  245. package/kits/hub-game/scripts/test-idle.mjs +361 -1
  246. package/kits/hub-game/scripts/test-interest-cap.mjs +36 -0
  247. package/kits/hub-game/scripts/test-interest-cells.mjs +493 -0
  248. package/kits/hub-game/scripts/test-interest-client.mjs +118 -0
  249. package/kits/hub-game/scripts/test-keys.mjs +46 -1
  250. package/kits/hub-game/scripts/test-labels.mjs +596 -0
  251. package/kits/hub-game/scripts/test-manifest.mjs +207 -0
  252. package/kits/hub-game/scripts/test-menu-client.mjs +480 -0
  253. package/kits/hub-game/scripts/test-menu.mjs +296 -0
  254. package/kits/hub-game/scripts/test-npcs.mjs +1718 -12
  255. package/kits/hub-game/scripts/test-object-entry.mjs +76 -0
  256. package/kits/hub-game/scripts/test-pack.mjs +7 -0
  257. package/kits/hub-game/scripts/test-picker.mjs +314 -0
  258. package/kits/hub-game/scripts/test-rehello.mjs +1039 -0
  259. package/kits/hub-game/scripts/test-relations-among.mjs +222 -0
  260. package/kits/hub-game/scripts/test-relations-refresh.mjs +188 -0
  261. package/kits/hub-game/scripts/test-shot.mjs +756 -0
  262. package/kits/hub-game/scripts/test-soundscape.mjs +5432 -0
  263. package/kits/hub-game/scripts/test-spin.mjs +314 -0
  264. package/kits/hub-game/scripts/test-standing.mjs +416 -0
  265. package/kits/hub-game/scripts/test-stuck.mjs +1903 -0
  266. package/kits/hub-game/scripts/test-tier-cells.mjs +706 -0
  267. package/kits/hub-game/scripts/test-tiers-render.mjs +339 -0
  268. package/kits/hub-game/scripts/test-tiers.mjs +477 -2
  269. package/kits/hub-game/scripts/test-toast-band.mjs +61 -0
  270. package/kits/hub-game/scripts/test-try-on.mjs +22 -22
  271. package/kits/hub-game/scripts/test-vis.mjs +343 -0
  272. package/kits/hub-game/scripts/test-visibility.mjs +134 -0
  273. package/kits/hub-game/scripts/test-yours-chrome.mjs +166 -0
  274. package/kits/hub-game/scripts/test-yours.mjs +372 -0
  275. package/kits/multiplayer-3d/CLAUDE.md +50 -0
  276. package/kits/multiplayer-3d/castle.json +5 -5
  277. package/kits/multiplayer-3d/code/client/avatars.js +7 -0
  278. package/kits/multiplayer-3d/code/client/gait.js +65 -0
  279. package/kits/multiplayer-3d/code/client/nameTags.js +59 -4
  280. package/kits/multiplayer-3d/code/options.js +5 -0
  281. package/kits/multiplayer-3d/code/server/ownership.js +10 -2
  282. package/kits/multiplayer-3d/code/server/sceneBodies.js +12 -0
  283. package/kits/multiplayer-3d/code/server/world.js +7 -0
  284. package/kits/multiplayer-3d/code/systems/multiplayer.js +74 -4
  285. package/kits/multiplayer-3d/package.json +2 -1
  286. package/kits/multiplayer-3d/scripts/fixtures/README.md +11 -0
  287. package/kits/multiplayer-3d/scripts/fixtures/ownership-legacy.json +2 -0
  288. package/kits/multiplayer-3d/scripts/ownership-harness.mjs +102 -0
  289. package/kits/multiplayer-3d/scripts/ownership-loader.mjs +46 -0
  290. package/kits/multiplayer-3d/scripts/ownership-worker.mjs +15 -0
  291. package/kits/multiplayer-3d/scripts/record-ownership-session.mjs +98 -0
  292. package/kits/multiplayer-3d/scripts/test-eligible-claims.mjs +167 -0
  293. package/kits/multiplayer-3d/scripts/test-own-name-tag.mjs +247 -0
  294. package/kits/physics-2d/CLAUDE.md +9 -0
  295. package/kits/physics-2d/castle.json +2 -2
  296. package/kits/physics-2d/engine/scene.js +253 -1
  297. package/kits/physics-2d/engine/skyKey.js +129 -0
  298. package/kits/physics-2d/engine/stillClock.js +106 -0
  299. package/kits/physics-2d/engine/updateBudget.js +21 -0
  300. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +326 -1
  301. package/kits/physics-3d/CLAUDE.md +1169 -30
  302. package/kits/physics-3d/behaviors/Player.jsx +629 -72
  303. package/kits/physics-3d/castle.json +3 -3
  304. package/kits/physics-3d/docs/pxmodel-format.md +8 -0
  305. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +69 -13
  306. package/kits/physics-3d/engine3d/actornode.js +86 -0
  307. package/kits/physics-3d/engine3d/animationBudget.js +23 -0
  308. package/kits/physics-3d/engine3d/editorWorld.js +6 -0
  309. package/kits/physics-3d/engine3d/emptynodes.js +232 -0
  310. package/kits/physics-3d/engine3d/framecap.js +96 -0
  311. package/kits/physics-3d/engine3d/gait.js +118 -0
  312. package/kits/physics-3d/engine3d/kithooks.js +47 -0
  313. package/kits/physics-3d/engine3d/look.js +507 -48
  314. package/kits/physics-3d/engine3d/lookbake.js +208 -0
  315. package/kits/physics-3d/engine3d/materialpresets.js +2 -0
  316. package/kits/physics-3d/engine3d/motion.js +39 -10
  317. package/kits/physics-3d/engine3d/nearshadows.js +37 -19
  318. package/kits/physics-3d/engine3d/optimize.js +9 -5
  319. package/kits/physics-3d/engine3d/orbitinput.js +487 -9
  320. package/kits/physics-3d/engine3d/orbitlens.js +48 -0
  321. package/kits/physics-3d/engine3d/ownmodel.js +213 -0
  322. package/kits/physics-3d/engine3d/pxmodel.js +42 -11
  323. package/kits/physics-3d/engine3d/shadowfade.js +882 -0
  324. package/kits/physics-3d/engine3d/sky.js +547 -0
  325. package/kits/physics-3d/engine3d/skylife.js +306 -0
  326. package/kits/physics-3d/engine3d/unchanged.js +11 -0
  327. package/kits/physics-3d/engine3d/viewrange.js +52 -0
  328. package/kits/physics-3d/engine3d/world3d.js +796 -69
  329. package/kits/physics-3d/main.jsx +5 -0
  330. package/kits/physics-3d/package.json +1 -1
  331. package/kits/physics-3d/scripts/look-baseline.mjs +155 -0
  332. package/kits/physics-3d/scripts/test-camera-orbit.mjs +2563 -80
  333. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +1 -1
  334. package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +435 -0
  335. package/kits/physics-3d/scripts/test-frame-cap.mjs +452 -0
  336. package/kits/physics-3d/scripts/test-gait.mjs +387 -0
  337. package/kits/physics-3d/scripts/test-look-bake.mjs +1056 -0
  338. package/kits/physics-3d/scripts/test-model-parse-cache.mjs +92 -0
  339. package/kits/physics-3d/scripts/test-near-shadows.mjs +3 -0
  340. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +1920 -0
  341. package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +545 -0
  342. package/kits/physics-3d/scripts/test-orbit-shot.mjs +583 -0
  343. package/kits/physics-3d/scripts/test-orbit-view.mjs +230 -0
  344. package/kits/physics-3d/scripts/test-skip-empty-nodes.mjs +845 -0
  345. package/kits/physics-3d/scripts/test-sky.mjs +2470 -0
  346. package/kits/physics-3d/scripts/test-static-actors.mjs +8 -1
  347. package/kits/physics-3d/scripts/test-static-scenery.mjs +2171 -0
  348. package/kits/physics-3d/scripts/test-steady-hover.mjs +2 -0
  349. package/kits/physics-3d/scripts/test-view-range.mjs +260 -0
  350. package/kits/physics-3d/systems/physics3d.js +383 -6
  351. package/kits/real-time/castle.json +2 -2
  352. package/kits/real-time/code/server/gameHooks.js +7 -0
  353. package/kits/real-time/code/server/session.js +97 -19
  354. package/package.json +2 -2
  355. package/dist/shell/assets/index-Cf61cNfT.css +0 -1
@@ -7,6 +7,9 @@ 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';
10
13
 
11
14
  const CARD_WIDTH = 500;
12
15
  const CARD_HEIGHT = 700;
@@ -128,6 +131,24 @@ function sceneDropsEmptyParts(data) {
128
131
  return data?.engine?.dropEmptyParts === true;
129
132
  }
130
133
 
134
+ // `"engine": { "staticActors": true }` at a scene file's top level, in a scene
135
+ // that also set `skipUnchangedActors`: the scene asks the engine not to visit,
136
+ // frame after frame, the actors its file marks `"static": true` (beside `id`
137
+ // and `components`), until something says one has changed (`scene.touch`). The
138
+ // 3d kit's CLAUDE.md has the terms. Off unless a scene says so with exactly
139
+ // `true`, and without the other key it does nothing.
140
+ function sceneKeepsStaticActors(data) {
141
+ return data?.engine?.staticActors === true && data?.engine?.skipUnchangedActors === true;
142
+ }
143
+
144
+ // What a behaviour class does on its own, frame by frame or when switched on
145
+ // or off. An actor with a component of such a class is never still.
146
+ const ACTS = ['update', 'onEnable', 'onDisable'];
147
+
148
+ function actsOnItsOwn(Behavior) {
149
+ return ACTS.some((hook) => typeof Behavior?.prototype?.[hook] === 'function');
150
+ }
151
+
131
152
  // `"engine": { "camera": { "follow": "rigid" } }` at a scene file's top level:
132
153
  // the scene asks the 3d kit's Player for a follow camera that moves with the
133
154
  // player rather than easing after it (its CLAUDE.md has the terms). Off unless
@@ -145,6 +166,26 @@ function sceneCameraControl(data) {
145
166
  return sceneCameraFollowsRigidly(data) && data.engine.camera.control === 'orbit' ? 'orbit' : null;
146
167
  }
147
168
 
169
+ // `"engine": { "look": { "bake": "deferred" } }` at a scene file's top level:
170
+ // the scene asks the 3d kit to draw its models before their look's occlusion
171
+ // and outlines are baked, and to bake those over the frames that follow (its
172
+ // CLAUDE.md has the terms). Off unless a scene says so with exactly
173
+ // "deferred". Nothing in this kit reads it.
174
+ function sceneBakesLookLater(data) {
175
+ return data?.engine?.look?.bake === 'deferred';
176
+ }
177
+
178
+ // `"engine": { "maxFps": 60 }` at a scene file's top level: the scene asks the
179
+ // 3d kit's player to run its frame (behaviours, physics, drawing) no more
180
+ // often than that on a display that refreshes faster (its CLAUDE.md has the
181
+ // terms). 0, no cap, unless a scene says so with a finite number from 30 to
182
+ // 240 (below 30 a frame would be longer than physics can step). Nothing in
183
+ // this kit reads it.
184
+ function sceneMaxFps(data) {
185
+ const fps = data?.engine?.maxFps;
186
+ return typeof fps === 'number' && Number.isFinite(fps) && fps >= 30 && fps <= 240 ? fps : 0;
187
+ }
188
+
148
189
  // Whether a Layout's z is plain data: its own stored value, or absent
149
190
  // altogether. One that is computed when read (an accessor, or carried by a
150
191
  // prototype) is left to the sort, which reads it in the sort's own order.
@@ -205,6 +246,148 @@ export class SceneRuntime {
205
246
  return this.#dropsEmptyParts;
206
247
  }
207
248
 
249
+ // Play-only: the 3d kit keeps empty actor nodes outside its draw scene.
250
+ #skipsEmptyNodes = false;
251
+
252
+ get skipsEmptyNodes() {
253
+ return this.#skipsEmptyNodes;
254
+ }
255
+
256
+ // Whether the loaded scene asked for `engine.staticActors` (and for
257
+ // `skipUnchangedActors`, without which it is not on). Set by `load`, as
258
+ // `skipsUnchangedActors` is.
259
+ #keepsStatic = false;
260
+
261
+ get keepsStaticActors() {
262
+ return this.#keepsStatic;
263
+ }
264
+
265
+ // For a scene that asked: the actors that are still, or null for a scene
266
+ // that did not. An actor is still when its scene file marked it
267
+ // `"static": true`, it has no `Body`, none of its components' classes acts on
268
+ // its own (`actsOnItsOwn`), and nothing has touched it since the load. The
269
+ // engine leaves a still actor out of its per-frame loops. `stillVersion`
270
+ // is a number no other state of this set, or of any other runtime's, has:
271
+ // it moves whenever the set changes. What the engine keeps about the set is
272
+ // kept against that number, and a frame on which the number is new to it
273
+ // visits every actor, as before.
274
+ #still = null;
275
+ #stillVersion = 0;
276
+ // The ids touched since the load, which no later reckoning of the set (a
277
+ // change of behaviour classes) lets back in.
278
+ #touched = null;
279
+ // `update`'s own adoption of the still set (stillClock.js has the rule and
280
+ // the StillKeeper that is the whole of it). Made the first time a scene
281
+ // that asks is loaded.
282
+ #keeper = null;
283
+
284
+ get stillActors() {
285
+ return this.#still;
286
+ }
287
+
288
+ get stillVersion() {
289
+ return this.#stillVersion;
290
+ }
291
+
292
+ // A function that returns the last `stillVersion` handed to any runtime: it
293
+ // moves whenever any scene's still set changes (stillClock.js). Handed out
294
+ // here so that what reads it need not import this kit by path.
295
+ get stillClock() {
296
+ return stillClock;
297
+ }
298
+
299
+ // A keeper of its own for a system that leaves still actors out of a pass
300
+ // (stillClock.js): the 3d kit's world and its physics system each ask for
301
+ // one, here, so that they need not import this kit by path.
302
+ newStillKeeper() {
303
+ return new StillKeeper();
304
+ }
305
+
306
+ // Says an actor is being changed by something the engine does not watch: a
307
+ // component written, added or removed, its node posed. The actor is not
308
+ // still from here to the next load; it is visited every frame, and followed
309
+ // from the frame of the touch on. Costs nothing for an actor that is not
310
+ // still, and does nothing in a scene that did not ask for `staticActors`.
311
+ touch(actorOrId) {
312
+ if (this.#still === null) return;
313
+ const actor = typeof actorOrId === 'string' ? this.actors.get(actorOrId) : actorOrId;
314
+ if (!actor) return;
315
+ this.#touched.add(actor.id);
316
+ if (this.#still.delete(actor)) this.#stillVersion = nextStillVersion();
317
+ }
318
+
319
+ // Touches every still actor at once: nothing is still from here to the next
320
+ // load. For a world that cannot leave actors alone (the 3d kit's scene
321
+ // editor, a world drawing copies of a model together).
322
+ releaseStill() {
323
+ if (this.#still === null || this.#still.size === 0) return;
324
+ for (const actor of this.#still) this.#touched.add(actor.id);
325
+ this.#noneStill();
326
+ }
327
+
328
+ // An empty still set under a new version: what stands while the set is
329
+ // being reckoned again, so that a reckoning that throws leaves no actor
330
+ // still rather than the ones that were.
331
+ #noneStill() {
332
+ this.#still = new Set();
333
+ this.#stillVersion = nextStillVersion();
334
+ this.#still.made = this.#stillVersion;
335
+ }
336
+
337
+ // The still set, reckoned from the scene's marks and the classes now
338
+ // registered. A new Set each time, so nothing kept against the old one is
339
+ // taken for this one.
340
+ #findStill() {
341
+ const still = new Set();
342
+ for (const actor of this.actors.values()) {
343
+ if (actor.static !== true || this.#touched.has(actor.id) || actor.components.Body) continue;
344
+ const names = Object.keys(actor.components);
345
+ if (names.some((name) => actsOnItsOwn(this.behaviors.get(name)))) continue;
346
+ still.add(actor);
347
+ }
348
+ this.#still = still;
349
+ this.#stillVersion = nextStillVersion();
350
+ // The version this Set was made at: the one number that stays with it
351
+ // while actors leave it.
352
+ still.made = this.#stillVersion;
353
+ }
354
+
355
+ // `update` for a scene that holds actors still: the same steps, with the
356
+ // still actors left out of the loop while this runtime has adopted its
357
+ // still set (stillClock.js). The whole update is one pass to the keeper: an
358
+ // ordinary one adopts only once the behaviours AND every system have run
359
+ // and returned, with no update entered from inside it and the still set
360
+ // unmoved; a throw anywhere in it, or an update inside it, leaves nothing
361
+ // adopted.
362
+ #updateHoldingStill(dt) {
363
+ const keeper = this.#keeper;
364
+ const pass = keeper.begin(this.#stillVersion);
365
+ let completed = false;
366
+ try {
367
+ this.time += dt;
368
+ updateTaps(this);
369
+ for (const actor of this.getActors()) {
370
+ // A still actor has no component that updates or is told of being
371
+ // switched on or off, and was run with the rest by the update that
372
+ // adopted. Once this update is no longer alone (a behaviour updated
373
+ // the scene from inside it) or the set has changed (one touched an
374
+ // actor, or loaded a scene), the rest of the loop runs every actor.
375
+ if (pass.settled && keeper.alone(pass, this.#stillVersion) && this.#still.has(actor)) continue;
376
+ const actorDt = actorUpdateDt(actor, dt);
377
+ if (actorDt === null) continue;
378
+ this.#syncEnabled(actor);
379
+ this.forEachBehavior(actor, (instance) => instance.update?.(actor, this, actorDt));
380
+ }
381
+ for (const system of this.systems) {
382
+ system.afterBehaviors?.(this, dt);
383
+ }
384
+ this.reapPointers();
385
+ completed = true;
386
+ } finally {
387
+ keeper.end(pass, completed, this.#stillVersion, () => (this.#still !== null && this.#still.size > 0 ? {} : null));
388
+ }
389
+ }
390
+
208
391
  // Whether the loaded scene asked for `engine.camera.follow: "rigid"`. Set
209
392
  // by `load`, as `skipsUnchangedActors` is.
210
393
  #cameraFollowsRigidly = false;
@@ -221,6 +404,39 @@ export class SceneRuntime {
221
404
  return this.#cameraControl;
222
405
  }
223
406
 
407
+ // Whether the loaded scene asked for `engine.look.bake: "deferred"`. Set by
408
+ // `load`, as `skipsUnchangedActors` is.
409
+ #bakesLookLater = false;
410
+
411
+ get bakesLookLater() {
412
+ return this.#bakesLookLater;
413
+ }
414
+
415
+ // What the loaded scene asked for with `engine.sky` (skyKey.js), or null:
416
+ // for a scene with no such key, and for one whose key is malformed. Set by
417
+ // `load`, as `skipsUnchangedActors` is. The 3d kit draws it.
418
+ #sky = null;
419
+
420
+ get sky() {
421
+ return this.#sky;
422
+ }
423
+
424
+ // For a scene with `engine.sky`: the zone the player is in and the sky
425
+ // being drawn, to read -- `{ id, blend, from, to }` (skyKey.js). The same
426
+ // object from a load to the next; the 3d kit keeps it current as it draws.
427
+ // null for a scene without the key, where nothing works it out.
428
+ get skyZone() {
429
+ return this.#sky === null ? null : this.#sky.zone;
430
+ }
431
+
432
+ // The frame rate the loaded scene capped its play loop at with
433
+ // `engine.maxFps`, or 0. Set by `load`, as `skipsUnchangedActors` is.
434
+ #maxFps = 0;
435
+
436
+ get maxFps() {
437
+ return this.#maxFps;
438
+ }
439
+
224
440
  // `files` is the live deck files map (path -> text), used to resolve every
225
441
  // actor's `blueprint` ref against the CURRENT blueprint file content -- not
226
442
  // a load-time snapshot -- so a blueprint edit propagates to every scene that
@@ -334,6 +550,8 @@ export class SceneRuntime {
334
550
  // `.constructor !== Behavior` is caught lazily by `#instanceFor` on next
335
551
  // access, so `this.state` survives a hot swap.
336
552
  setBehaviors(classes) {
553
+ // No actor is still while the classes change under them.
554
+ if (this.#still !== null) this.#noneStill();
337
555
  this.behaviors = behaviorMapFrom(classes);
338
556
  for (const actor of this.actors.values()) {
339
557
  for (const [name, Behavior] of this.behaviors) {
@@ -344,9 +562,19 @@ export class SceneRuntime {
344
562
  }
345
563
  }
346
564
  }
565
+ // A class may have gained or lost an `update`.
566
+ if (this.#still !== null) this.#findStill();
347
567
  }
348
568
 
349
569
  load(sceneData) {
570
+ // No actor of the scene being left is still from here on, whether or not
571
+ // the load completes.
572
+ if (this.#still !== null) {
573
+ this.#still = null;
574
+ this.#touched = null;
575
+ this.#stillVersion = nextStillVersion();
576
+ this.#keeper.interrupt();
577
+ }
350
578
  // Reset registered systems (e.g. physics) so a reload/restart/scene
351
579
  // transition starts from the authored layout -- otherwise a system holding
352
580
  // simulation state (body positions, joints) would carry it across the load.
@@ -356,8 +584,16 @@ export class SceneRuntime {
356
584
  this.#skipUnchanged = sceneSkipsUnchangedActors(this.data);
357
585
  this.#nearShadowDistance = sceneNearShadowDistance(this.data);
358
586
  this.#dropsEmptyParts = sceneDropsEmptyParts(this.data);
587
+ this.#skipsEmptyNodes = this.data?.engine?.skipEmptyNodes === true;
588
+ this.#keepsStatic = sceneKeepsStaticActors(this.data);
359
589
  this.#cameraFollowsRigidly = sceneCameraFollowsRigidly(this.data);
360
590
  this.#cameraControl = sceneCameraControl(this.data);
591
+ // Orbit extras must be available before any code in the new scene runs.
592
+ // Keep registrations across loads, and allocate nothing for keyless worlds.
593
+ if (this.#cameraControl === 'orbit' && this.three) this.three.ownModelWith ??= new Set();
594
+ this.#bakesLookLater = sceneBakesLookLater(this.data);
595
+ this.#sky = readSkyKey(this.data);
596
+ this.#maxFps = sceneMaxFps(this.data);
361
597
  this.actors = new Map();
362
598
  for (const actor of this.data.actors ?? []) {
363
599
  this.#initActor(actor);
@@ -376,6 +612,11 @@ export class SceneRuntime {
376
612
  }
377
613
  }
378
614
  }
615
+ if (this.#keepsStatic) {
616
+ this.#keeper ??= new StillKeeper();
617
+ this.#touched = new Set();
618
+ this.#findStill();
619
+ }
379
620
  }
380
621
 
381
622
  // Read and parse a scene file by name, returning its scene data. Use this
@@ -516,6 +757,9 @@ export class SceneRuntime {
516
757
  components[name] = Behavior ? { ...Behavior.defaultProps, ...props } : { ...props };
517
758
  }
518
759
  const next = { ...actor, id, components };
760
+ // Only an actor of the scene's file can be still, whatever a spawned one's
761
+ // own data says.
762
+ if (this.#touched !== null) this.#touched.add(id);
519
763
  this.#initActor(next);
520
764
  this.data.actors.push(next);
521
765
  this.actors.set(id, next);
@@ -535,6 +779,7 @@ export class SceneRuntime {
535
779
  despawnActor(actorId) {
536
780
  const actor = this.actors.get(actorId);
537
781
  if (!actor) return false;
782
+ if (this.#still !== null && this.#still.delete(actor)) this.#stillVersion = nextStillVersion();
538
783
  this.actors.delete(actorId);
539
784
  const idx = this.data.actors.findIndex((a) => a.id === actorId);
540
785
  if (idx !== -1) this.data.actors.splice(idx, 1);
@@ -683,13 +928,20 @@ export class SceneRuntime {
683
928
  }
684
929
 
685
930
  update(dt) {
931
+ // A scene that holds actors still (`"engine": { "staticActors": true }`).
932
+ if (this.#still !== null) {
933
+ this.#updateHoldingStill(dt);
934
+ return;
935
+ }
686
936
  this.time += dt;
687
937
  // Before controls, so a tap on an actor that implements `onTap` claims the
688
938
  // finger first. Targeted controls (Draggable) can still take it afterward.
689
939
  updateTaps(this);
690
940
  for (const actor of this.getActors()) {
941
+ const actorDt = actorUpdateDt(actor, dt);
942
+ if (actorDt === null) continue;
691
943
  this.#syncEnabled(actor);
692
- this.forEachBehavior(actor, (instance) => instance.update?.(actor, this, dt));
944
+ this.forEachBehavior(actor, (instance) => instance.update?.(actor, this, actorDt));
693
945
  }
694
946
  // Behaviors have expressed their intent (velocities, forces) for this frame;
695
947
  // 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
+ }
@@ -0,0 +1,106 @@
1
+ // What the engine keeps, and how, for scenes that hold actors still
2
+ // (`"engine": { "staticActors": true }`; scene.js has the still set, the 3d
3
+ // kit's CLAUDE.md the terms). Two things, used the same way by everything that
4
+ // leaves still actors out of a per-frame pass: the runtime's `update`, the 3d
5
+ // world's pass over the actors, and the 3d physics pass.
6
+ //
7
+ // THE CLOCK. The versions of every scene's still set come from one sequence,
8
+ // so a number names one state of one runtime's still set, and `stillClock()`
9
+ // moves whenever any runtime's still set changes -- an actor touched or
10
+ // despawned, a scene loaded, the behaviour classes changed. The 3d kit's
11
+ // frozen nodes read it: a touch thaws them at once.
12
+ //
13
+ // THE KEEPER. A system may leave still actors out of a pass only while it has
14
+ // ADOPTED the still set, and the rule for that is one rule:
15
+ //
16
+ // A system adopts the still set only AFTER an ordinary pass (every actor)
17
+ // has completed without throwing. While any pass, or anything it calls back
18
+ // into, is running, no still state is trusted. Any interruption -- a throw,
19
+ // a pass entered from inside another, by this runtime or any other -- leaves
20
+ // the next pass ordinary.
21
+ //
22
+ // A StillKeeper is that rule and nothing else; each system has one and never
23
+ // keeps an adoption anywhere but in it:
24
+ //
25
+ // - `passes` counts every entry into the system's pass (settled or ordinary,
26
+ // whichever runtime, nested or not) and every other interruption a system
27
+ // reports (`interrupt`). It only goes up. (A throw needs no count of its
28
+ // own: the pass it leaves does not complete, and a pass around that one
29
+ // saw the entry.)
30
+ // - `begin(version)` counts the entry and says whether this pass may be
31
+ // settled: only when there is an adoption, made (or last confirmed) at the
32
+ // count as it stood just before this entry, for this very `version` of the
33
+ // still set. If not, the adoption is dropped THERE, before the pass does
34
+ // anything. A system with reasons of its own to refuse (`demote`) drops it
35
+ // the same way.
36
+ // - `end(pass, completed, version, adopt)` is called once, in the `finally`
37
+ // of the WHOLE operation. Unless the pass completed, `passes` is still the
38
+ // pass's own count (nobody entered, nothing was reported), no other pass of
39
+ // this system is running, and the still set's version is what it was at
40
+ // `begin`, the adoption is dropped. Otherwise a settled pass confirms its
41
+ // adoption at the new count, and an ordinary one records what `adopt()`
42
+ // returns (or nothing, if that is null).
43
+ //
44
+ // So nothing is ever put back: a pass that was interrupted leaves no adoption,
45
+ // whoever interrupted it and whatever they caught. An adoption holds numbers
46
+ // and whatever plain data its system adds; it names a runtime only by the
47
+ // version of its still set, which no other runtime's can equal.
48
+ let last = 0;
49
+
50
+ export function nextStillVersion() {
51
+ last += 1;
52
+ return last;
53
+ }
54
+
55
+ export function stillClock() {
56
+ return last;
57
+ }
58
+
59
+ export class StillKeeper {
60
+ passes = 0;
61
+ running = 0;
62
+ adopted = null;
63
+
64
+ begin(version) {
65
+ const before = this.passes;
66
+ this.passes += 1;
67
+ this.running += 1;
68
+ const adopted = this.adopted;
69
+ const settled = adopted !== null && adopted.at === before && adopted.version === version;
70
+ if (!settled) this.adopted = null;
71
+ return { mine: this.passes, version, settled };
72
+ }
73
+
74
+ // Whether `pass` is still the only thing that has happened to this system
75
+ // since it began, on the still set it began with.
76
+ alone(pass, version) {
77
+ return this.passes === pass.mine && version === pass.version;
78
+ }
79
+
80
+ // A pass that began settled finds it may not be after all.
81
+ demote(pass) {
82
+ pass.settled = false;
83
+ this.adopted = null;
84
+ }
85
+
86
+ // Something the pass count does not see by itself: code that is not the
87
+ // engine's is about to run inside a pass, or the system is being reset.
88
+ interrupt() {
89
+ this.passes += 1;
90
+ this.adopted = null;
91
+ }
92
+
93
+ end(pass, completed, version, adopt) {
94
+ this.running -= 1;
95
+ if (!completed || this.running !== 0 || !this.alone(pass, version)) {
96
+ this.adopted = null;
97
+ return;
98
+ }
99
+ if (pass.settled) {
100
+ this.adopted.at = this.passes;
101
+ return;
102
+ }
103
+ const data = adopt();
104
+ this.adopted = data ? { ...data, at: this.passes, version } : null;
105
+ }
106
+ }
@@ -0,0 +1,21 @@
1
+ // Optional client-owned cadence, in seconds. No flag means the original dt.
2
+ // Events and systems still run each frame; only this actor's update is budgeted.
3
+ const clocks = new WeakMap();
4
+ export function actorUpdateDt(actor, dt) {
5
+ const every = actor.runtime?.updateEvery;
6
+ if (!(Number.isFinite(every) && every > 0) || !(dt > 0)) {
7
+ const elapsed = clocks.get(actor)?.elapsed ?? 0;
8
+ clocks.delete(actor);
9
+ return elapsed ? dt + elapsed : dt;
10
+ }
11
+ const prior = clocks.get(actor);
12
+ if (!prior || prior.every !== every) {
13
+ clocks.set(actor, { every, elapsed: 0 });
14
+ return dt + (prior?.elapsed ?? 0);
15
+ }
16
+ prior.elapsed += dt;
17
+ if (prior.elapsed + 1e-9 < every) return null;
18
+ const elapsed = prior.elapsed;
19
+ prior.elapsed = 0;
20
+ return elapsed;
21
+ }