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
@@ -0,0 +1,547 @@
1
+ // Scenes that set `"engine": { "sky": { ... } }` (physics-2d engine/skyKey.js
2
+ // reads the key and has its shape; CLAUDE.md has the terms).
3
+ //
4
+ // The engine clears to black and has no sky. For a scene that asks, a sky is
5
+ // drawn behind everything: the sky of the zone the player stands in, one
6
+ // picture (or one flat colour) over the whole dome, turning into the next
7
+ // zone's over `fade` seconds when the player crosses into it.
8
+ //
9
+ // A world playing a scene without the key has nothing of this: `world.sky`
10
+ // is null, and `renderWorld` runs one read and one null check more than it
11
+ // did. With the key, what the mode needs is its own -- one mesh, its
12
+ // material, at most one texture per zone with ready art -- kept on `world.sky`.
13
+ //
14
+ // The invariant (skylife.js, which has how it holds and is the only place
15
+ // that attaches, detaches or disposes anything):
16
+ //
17
+ // The dome and its resources are attached, detached and disposed only by
18
+ // the outermost render of their world, or with no render of that world in
19
+ // progress. Nothing a callback does (re-enter, throw, load, dispose) can
20
+ // leave a dome in the scene graph, a disposed resource in a render list,
21
+ // or a sky record alive past its key.
22
+ //
23
+ // So the dome is in the scene graph only while a frame of its own scene is
24
+ // being drawn, and outside that the scene graph is as the engine leaves it:
25
+ // nothing that walks or reads it (the actor sync, a deck's own traversal,
26
+ // picking, the look bake, hub-game's tiers) ever meets the sky.
27
+ //
28
+ // What it is, while it is drawn:
29
+ //
30
+ // - One mesh that is not an actor: no node, no `userData.actorId`, no
31
+ // collider (the orbit camera's reach is physics, which has never heard of
32
+ // it). `castShadow` is off, so the shadow pass, the sun's own or the near
33
+ // shadows', does not draw it: it is drawn in the colour pass only.
34
+ // - A dome round the camera: its vertex shader turns the dome with the
35
+ // camera and never moves it, and puts every vertex on the far plane, so
36
+ // the sky is behind everything at any distance and is never clipped. It
37
+ // is drawn after every opaque thing (`renderOrder`) with the depth test
38
+ // on and depth writes off: only the pixels nothing else covered are
39
+ // shaded, once.
40
+ // - Unlit: the fragment is the zone's picture at that direction (one
41
+ // texture read; two while one zone turns into another), or the zone's
42
+ // flat colour. No light, shadow, fog or tone mapping touches it.
43
+ //
44
+ // A zone's picture is a deck image (`art`, a path in the deck: the bundler's
45
+ // media glob hands it over as `runtime.sprites[path]`, a `data:` URI in a
46
+ // published deck; nothing is fetched). Across, it is the bearing, north (-z)
47
+ // at the left edge and east (+x) a quarter of the way along; down, it is the
48
+ // height, straight overhead in the first row and `below` degrees under the
49
+ // horizon in the last, with the last row again below that. A texture is made
50
+ // as soon as its art is ready, decoded to a bitmap when supported, and
51
+ // uploaded one per frame ahead of use. It stays until that art changes or
52
+ // the sky ends. A zone with no `art`,
53
+ // with an image that has not arrived or failed, or with an `art` that is not
54
+ // an image (a `.sprite`), is its `color`.
55
+ //
56
+ // Which zone: the local Player's Transform (the first actor with a `Player`
57
+ // component), not the camera, which the orbit camera carries 37 m off. A
58
+ // player is in a box from its edge, and stays in it until `edge` metres
59
+ // outside. No Player, or one in no box: the zone without a box.
60
+ //
61
+ // The fade (`stepFade`): from the zone drawn to the zone the player is in,
62
+ // `fade` seconds, by the clock between frames (a gap of more than
63
+ // FRAME_MOST_S counts as that much). Turning back mid-fade runs it
64
+ // backwards from where it is. Walking on into a third zone mid-fade lets the
65
+ // fade finish and then starts the next. Nothing fades at a scene's first
66
+ // frame, or when the player is somewhere else at once (more than SNAP_M from
67
+ // where the frame before had them: a door, a put): the sky is the zone's.
68
+ //
69
+ // State is per world (`world.sky`) and belongs to one load of one scene (it
70
+ // is keyed by the object the load read the key into): another scene, the
71
+ // same scene loaded again, a scene without the key, a frame with no runtime
72
+ // (an editor's), `disposeWorld`, or a frame that throws, and it is disposed
73
+ // and gone (skylife.js says exactly when); the next keyed frame starts again
74
+ // from nothing, without a fade. `runtime.skyZone` (skyKey.js) is kept
75
+ // current here for anyone to read.
76
+ import * as THREE from 'three';
77
+ import { skyFrame } from './skylife.js';
78
+
79
+ export { leaveSky } from './skylife.js';
80
+
81
+ // A longer gap between two frames than this moves the fade only this far.
82
+ export const FRAME_MOST_S = 0.25;
83
+ // Further than this from where the last frame had them, the player did not walk.
84
+ export const SNAP_M = 8;
85
+
86
+ // The dome: rings of vertices by height in degrees (the first and the ring at
87
+ // `below` are added in `domeGeometry`), and how many round.
88
+ const RINGS_UP = [0, 8, 20, 35, 50, 65, 80];
89
+ const ROUND = 24;
90
+ const RADIUS = 10;
91
+
92
+ const VERTEX = /* glsl */ `
93
+ varying vec2 vUv;
94
+ void main() {
95
+ vUv = uv;
96
+ vec4 clip = projectionMatrix * vec4(mat3(viewMatrix) * position, 1.0);
97
+ gl_Position = clip.xyww;
98
+ }
99
+ `;
100
+
101
+ const FRAGMENT = /* glsl */ `
102
+ uniform sampler2D mapFrom;
103
+ uniform sampler2D mapTo;
104
+ uniform vec3 colorFrom;
105
+ uniform vec3 colorTo;
106
+ uniform float hasFrom;
107
+ uniform float hasTo;
108
+ uniform float blend;
109
+ varying vec2 vUv;
110
+ void main() {
111
+ vec3 sky = hasFrom > 0.5 ? texture2D(mapFrom, vUv).rgb : colorFrom;
112
+ if (blend > 0.0) {
113
+ vec3 next = hasTo > 0.5 ? texture2D(mapTo, vUv).rgb : colorTo;
114
+ sky = mix(sky, next, blend);
115
+ }
116
+ gl_FragColor = vec4(sky, 1.0);
117
+ #include <colorspace_fragment>
118
+ }
119
+ `;
120
+
121
+ //
122
+ // Which zone
123
+ //
124
+
125
+ function inBox(box, x, z, pad) {
126
+ return x >= box[0] - pad && x <= box[2] + pad && z >= box[1] - pad && z <= box[3] + pad;
127
+ }
128
+
129
+ // The index of the zone a point is in. `current` is the zone it was in a
130
+ // frame ago (or -1): it is still in that one until `edge` outside its box.
131
+ export function zoneAt(key, x, z, current = -1) {
132
+ if (!(Number.isFinite(x) && Number.isFinite(z))) return key.home;
133
+ const zones = key.zones;
134
+ const held = zones[current]?.box;
135
+ if (held && inBox(held, x, z, key.edge)) return current;
136
+ for (let i = 0; i < zones.length; i++) {
137
+ if (zones[i].box && inBox(zones[i].box, x, z, 0)) return i;
138
+ }
139
+ return key.home;
140
+ }
141
+
142
+ //
143
+ // The fade
144
+ //
145
+
146
+ // `fade` is { from, to, mix, next }: the sky drawn is zone `from` turning
147
+ // into zone `to`, `mix` of the way (0 at rest, when `to` is `from`); `next`
148
+ // is a zone waiting for this fade to end, or -1. One frame of it, `seconds`
149
+ // long, toward `target`, a whole fade taking `whole` seconds.
150
+ export function stepFade(fade, target, seconds, whole) {
151
+ if (fade.mix === 0) {
152
+ // At rest.
153
+ fade.next = -1;
154
+ if (target === fade.from) return;
155
+ fade.to = target;
156
+ } else if (target === fade.from) {
157
+ // Turned back: the same fade, the other way, from where it is.
158
+ fade.from = fade.to;
159
+ fade.to = target;
160
+ fade.mix = 1 - fade.mix;
161
+ fade.next = -1;
162
+ } else {
163
+ fade.next = target === fade.to ? -1 : target;
164
+ }
165
+ fade.mix += seconds / whole;
166
+ // Sums of frame times fall a hair short of the whole.
167
+ if (fade.mix >= 1 - 1e-9) {
168
+ fade.from = fade.to;
169
+ fade.mix = 0;
170
+ if (fade.next !== -1 && fade.next !== fade.from) {
171
+ fade.to = fade.next;
172
+ // The next fade starts on the frame after this one.
173
+ fade.mix = Number.MIN_VALUE;
174
+ }
175
+ fade.next = -1;
176
+ }
177
+ }
178
+
179
+ function snapFade(fade, zone) {
180
+ fade.from = zone;
181
+ fade.to = zone;
182
+ fade.mix = 0;
183
+ fade.next = -1;
184
+ }
185
+
186
+ //
187
+ // The dome
188
+ //
189
+
190
+ // Unit directions by bearing (north is -z, east +x) and height, with the
191
+ // picture's u across and v up it. The two poles are a vertex a segment, so
192
+ // each triangle at a pole has the u of its own middle.
193
+ function domeGeometry(below) {
194
+ const ups = [-90, ...(below > 0 ? [-below] : []), ...RINGS_UP, 90];
195
+ const positions = [];
196
+ const uvs = [];
197
+ const index = [];
198
+ const rows = [];
199
+ for (const up of ups) {
200
+ const pole = Math.abs(up) === 90;
201
+ const count = pole ? ROUND : ROUND + 1;
202
+ const e = (up * Math.PI) / 180;
203
+ const v = Math.max(0, (up + below) / (90 + below));
204
+ rows.push({ start: positions.length / 3, pole });
205
+ for (let i = 0; i < count; i++) {
206
+ const u = (pole ? i + 0.5 : i) / ROUND;
207
+ const b = u * 2 * Math.PI;
208
+ positions.push(RADIUS * Math.sin(b) * Math.cos(e), RADIUS * Math.sin(e), -RADIUS * Math.cos(b) * Math.cos(e));
209
+ uvs.push(u, v);
210
+ }
211
+ }
212
+ for (let r = 0; r + 1 < rows.length; r++) {
213
+ const low = rows[r];
214
+ const high = rows[r + 1];
215
+ for (let i = 0; i < ROUND; i++) {
216
+ if (low.pole) index.push(low.start + i, high.start + i, high.start + i + 1);
217
+ else if (high.pole) index.push(low.start + i, high.start + i, low.start + i + 1);
218
+ else index.push(low.start + i, high.start + i, low.start + i + 1, low.start + i + 1, high.start + i, high.start + i + 1);
219
+ }
220
+ }
221
+ const geometry = new THREE.BufferGeometry();
222
+ geometry.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3));
223
+ geometry.setAttribute('uv', new THREE.Float32BufferAttribute(uvs, 2));
224
+ geometry.setIndex(index);
225
+ return geometry;
226
+ }
227
+
228
+ function makeSky(key, world) {
229
+ const material = new THREE.ShaderMaterial({
230
+ name: 'engine.sky',
231
+ vertexShader: VERTEX,
232
+ fragmentShader: FRAGMENT,
233
+ uniforms: {
234
+ mapFrom: { value: null },
235
+ mapTo: { value: null },
236
+ colorFrom: { value: new THREE.Color() },
237
+ colorTo: { value: new THREE.Color() },
238
+ hasFrom: { value: 0 },
239
+ hasTo: { value: 0 },
240
+ blend: { value: 0 },
241
+ },
242
+ // Seen from inside whichever way its faces wind.
243
+ side: THREE.DoubleSide,
244
+ depthWrite: false,
245
+ fog: false,
246
+ toneMapped: false,
247
+ });
248
+ const mesh = new THREE.Mesh(domeGeometry(key.below), material);
249
+ mesh.name = 'engine.sky';
250
+ mesh.frustumCulled = false;
251
+ mesh.castShadow = false;
252
+ mesh.receiveShadow = false;
253
+ mesh.matrixAutoUpdate = false;
254
+ // After every opaque thing: only what they left uncovered is shaded.
255
+ mesh.renderOrder = Number.MAX_SAFE_INTEGER;
256
+ // zone index -> { art, texture, ready, pending, uploaded, bitmap }
257
+ // Memory bound: one texture per zone with art (the hub's five 1024x256
258
+ // RGBA skies use about 1 MB each on the GPU; no mipmaps), plus its bitmap.
259
+ const textures = new Map();
260
+ const canvas = world.renderer?.domElement;
261
+ const restored = () => {
262
+ // three.js recreates its GPU texture cache after a context restore.
263
+ // Retained pictures must go through the preload queue again.
264
+ for (const held of textures.values()) held.uploaded = false;
265
+ };
266
+ canvas?.addEventListener('webglcontextrestored', restored);
267
+ // Textures the step let go, for skylife.js to dispose (its C3).
268
+ const shed = [];
269
+ return {
270
+ key,
271
+ mesh,
272
+ material,
273
+ textures,
274
+ shed,
275
+ released: false,
276
+ warnings: (world.skyWarnings ??= new Set()),
277
+ fade: { from: key.home, to: key.home, mix: 0, next: -1 },
278
+ // The zone the player is in, or -1 before the first frame.
279
+ zone: -1,
280
+ player: null,
281
+ last: null,
282
+ at: null,
283
+ // What skylife.js disposes, and what it resets: `skyZone` says again
284
+ // what it said before a frame was drawn.
285
+ owned: () => [...[...textures.values()].map((held) => held.texture), mesh.geometry, material],
286
+ forget() {
287
+ this.released = true;
288
+ canvas?.removeEventListener('webglcontextrestored', restored);
289
+ const home = key.zones[key.home].id;
290
+ Object.assign(key.state, { id: home, blend: 0, from: home, to: home });
291
+ },
292
+ };
293
+ }
294
+
295
+ //
296
+ // A frame
297
+ //
298
+
299
+ function playerOf(sky, runtime) {
300
+ const held = sky.player;
301
+ if (held && held.components?.Player && runtime.getActor?.(held.id) === held) return held;
302
+ sky.player = runtime.actorWith?.('Player') ?? null;
303
+ return sky.player;
304
+ }
305
+
306
+ const ACCESSOR = Symbol('sky art accessor');
307
+ function ownValue(object, name) {
308
+ const property = Object.getOwnPropertyDescriptor(object, name);
309
+ return property && !Object.hasOwn(property, 'value') ? ACCESSOR : property?.value;
310
+ }
311
+
312
+ function plain(object) {
313
+ if (object === null || typeof object !== 'object') return false;
314
+ const prototype = Object.getPrototypeOf(object);
315
+ return prototype === Object.prototype || prototype === null;
316
+ }
317
+
318
+ function warnArt(sky, zone) {
319
+ const key = `${zone.id.length}:${zone.id}${zone.art}`;
320
+ if (sky.warnings.has(key)) return;
321
+ sky.warnings.add(key);
322
+ console.warn(`engine.sky zone "${zone.id}" art "${zone.art}" is ignored: expected a plain art record with own data properties.`);
323
+ }
324
+
325
+ // Art tables and records are engine data. Inspect descriptors, never invoke
326
+ // an accessor. Replacing the engine's table with a Proxy is outside the
327
+ // contract, just as it is for the engine's other art readers.
328
+ function skyArt(sky, runtime, zone) {
329
+ if (zone.art === null) return null;
330
+ const sprites = runtime.sprites;
331
+ if (sprites === null || sprites === undefined) return null;
332
+ if (!plain(sprites)) { warnArt(sky, zone); return null; }
333
+ const art = ownValue(sprites, zone.art);
334
+ if (art === null || art === undefined) return null;
335
+ if (!plain(art)) { warnArt(sky, zone); return null; }
336
+ const kind = ownValue(art, 'kind');
337
+ const ready = ownValue(art, 'ready');
338
+ const failed = ownValue(art, 'failed');
339
+ const image = ownValue(art, 'image');
340
+ if (kind === ACCESSOR || ready === ACCESSOR || failed === ACCESSOR || image === ACCESSOR) { warnArt(sky, zone); return null; }
341
+ return { art, image: kind === 'image' && ready === true && failed !== true ? image : null };
342
+ }
343
+
344
+ // Bitmap results only change an unuploaded texture. If a fade needed the
345
+ // original image before decoding finished, keep that upload: no blank frame
346
+ // and no second upload on a later crossing. Disposal is still skylife's.
347
+ function decodeTexture(sky, runtime, index, held, image) {
348
+ if (typeof globalThis.createImageBitmap !== 'function') return;
349
+ held.pending = true;
350
+ let decoding;
351
+ try {
352
+ // WebGL ignores flipY/premultiplyAlpha for ImageBitmap. Bake the same
353
+ // vertical flip as Texture's default flipY=true into the bitmap: image
354
+ // row zero still samples at dome v=1 (overhead), the last at v=0.
355
+ decoding = globalThis.createImageBitmap(image, { imageOrientation: 'flipY', premultiplyAlpha: 'none', colorSpaceConversion: 'none' });
356
+ } catch {
357
+ held.pending = false;
358
+ return;
359
+ }
360
+ Promise.resolve(decoding).then((bitmap) => {
361
+ held.pending = false;
362
+ if (sky.released || sky.textures.get(index) !== held || held.uploaded || skyArt(sky, runtime, sky.key.zones[index])?.art !== held.art) {
363
+ bitmap.close();
364
+ return;
365
+ }
366
+ held.bitmap = bitmap;
367
+ held.texture.image = bitmap;
368
+ held.texture.flipY = false;
369
+ }, () => { held.pending = false; });
370
+ }
371
+
372
+ // A zone's texture, made when its art is ready; null while its zone is its
373
+ // flat colour. Every zone is checked, including ones outside the fade.
374
+ function textureOf(sky, runtime, index) {
375
+ const zone = sky.key.zones[index];
376
+ const read = skyArt(sky, runtime, zone);
377
+ const usable = read?.art ?? null;
378
+ const held = sky.textures.get(index);
379
+ if (held && held.art === usable) {
380
+ // Readiness changes can hide art, but only a different art object (or
381
+ // its removal) sheds the cache and runs disposal listeners.
382
+ held.ready = Boolean(read.image);
383
+ return held.ready ? held.texture : null;
384
+ }
385
+ if (held) {
386
+ // Let go, not disposed: disposal runs listeners, and is skylife.js's.
387
+ sky.textures.delete(index);
388
+ sky.shed.push(held.texture);
389
+ }
390
+ if (!read?.image) return null;
391
+ const texture = new THREE.Texture(read.image);
392
+ texture.colorSpace = THREE.SRGBColorSpace;
393
+ texture.wrapS = THREE.RepeatWrapping;
394
+ texture.wrapT = THREE.ClampToEdgeWrapping;
395
+ // A sky is always drawn larger than its picture: no smaller copies.
396
+ texture.magFilter = THREE.LinearFilter;
397
+ texture.minFilter = THREE.LinearFilter;
398
+ texture.generateMipmaps = false;
399
+ texture.needsUpdate = true;
400
+ const entry = { art: usable, texture, ready: true, pending: false, uploaded: false, bitmap: null };
401
+ texture.addEventListener('dispose', () => {
402
+ entry.bitmap?.close();
403
+ entry.bitmap = null;
404
+ });
405
+ sky.textures.set(index, entry);
406
+ decodeTexture(sky, runtime, index, entry, read.image);
407
+ return texture;
408
+ }
409
+
410
+ // Only preload one per outermost frame. Pending inactive pictures wait for
411
+ // their bitmap; a picture needed now uses the original image immediately.
412
+ function uploadSky(sky, renderer) {
413
+ const fade = sky.fade;
414
+ const active = (index) => index === fade.from || (fade.mix > 0 && index === fade.to);
415
+ if (renderer?.initTexture) {
416
+ let next = null;
417
+ for (const [index, held] of sky.textures) {
418
+ if (!held.ready || held.uploaded) continue;
419
+ if (active(index)) { next = held; break; }
420
+ if (!next && !held.pending) next = held;
421
+ }
422
+ if (next) {
423
+ renderer.initTexture(next.texture);
424
+ next.uploaded = true;
425
+ }
426
+ }
427
+ // The draw uploads any active fallback not preloaded above. If both fade
428
+ // images arrive together, drawing them exactly as before requires both
429
+ // uploads; the one-per-frame budget is for proactive uploads. Remember
430
+ // that use so a late bitmap cannot cause another upload. This also works
431
+ // for renderers without initTexture, via three.js's ordinary lazy upload.
432
+ for (const [index, held] of sky.textures) if (held.ready && active(index)) held.uploaded = true;
433
+ }
434
+
435
+ function stepSky(sky, runtime, now, renderer) {
436
+ const key = sky.key;
437
+ const t = playerOf(sky, runtime)?.components?.Transform;
438
+ const x = t ? t.x : NaN;
439
+ const z = t ? t.z : NaN;
440
+ const here = Number.isFinite(x) && Number.isFinite(z);
441
+ const moved = here && sky.last ? Math.hypot(x - sky.last.x, z - sky.last.z) : 0;
442
+ const fresh = sky.zone === -1 || moved > SNAP_M || here !== (sky.last !== null);
443
+ sky.last = here ? { x, z } : null;
444
+ sky.zone = zoneAt(key, x, z, fresh ? -1 : sky.zone);
445
+ const seconds = sky.at === null ? 0 : Math.max(0, Math.min(FRAME_MOST_S, (now - sky.at) / 1000));
446
+ sky.at = now;
447
+ const fade = sky.fade;
448
+ if (fresh) snapFade(fade, sky.zone);
449
+ else stepFade(fade, sky.zone, seconds, key.fade);
450
+
451
+ for (let index = 0; index < key.zones.length; index++) textureOf(sky, runtime, index);
452
+ uploadSky(sky, renderer);
453
+ const uniforms = sky.material.uniforms;
454
+ const fromHeld = sky.textures.get(fade.from);
455
+ const toHeld = sky.textures.get(fade.to);
456
+ const from = fromHeld?.ready ? fromHeld.texture : null;
457
+ const to = toHeld?.ready ? toHeld.texture : null;
458
+ uniforms.mapFrom.value = from;
459
+ uniforms.mapTo.value = to;
460
+ uniforms.hasFrom.value = from ? 1 : 0;
461
+ uniforms.hasTo.value = to ? 1 : 0;
462
+ uniforms.colorFrom.value.set(key.zones[fade.from].color);
463
+ uniforms.colorTo.value.set(key.zones[fade.to].color);
464
+ uniforms.blend.value = fade.mix;
465
+
466
+ const state = key.state;
467
+ state.id = key.zones[sky.zone].id;
468
+ state.from = key.zones[fade.from].id;
469
+ state.to = key.zones[fade.to].id;
470
+ state.blend = fade.mix;
471
+ }
472
+
473
+ // `renderWorld` for a world whose scene has the key, or which has a record
474
+ // left from one that had: `draw(world, runtime)` is the frame as it is drawn
475
+ // without the key. skylife.js decides whether this frame steps and shows the
476
+ // sky, is drawn with it as it is, or is drawn without. `calloutFor` supplies
477
+ // the world's disposal bracket only when skylife makes a record.
478
+ export function renderWithSky(world, runtime, draw, now = performance.now(), calloutFor) {
479
+ skyFrame(
480
+ world,
481
+ runtime,
482
+ () => draw(world, runtime),
483
+ makeSky,
484
+ (sky) => stepSky(sky, runtime, now, world.renderer),
485
+ calloutFor
486
+ );
487
+ }
488
+
489
+ // Only engine.view asks for this. The colours are linear, like the dome's
490
+ // uniforms and decoded sRGB textures, and use exactly its current fade.
491
+ // Keep sampling resources on the view record: existing skies do no extra
492
+ // work. A texture's nearest horizon row (top = overhead) is reduced to one
493
+ // representative pixel across all bearings, once per art entry. Use the
494
+ // original image, not the vertically flipped ImageBitmap used for upload.
495
+ export function skyHorizonColor(world, range) {
496
+ const sky = world.sky;
497
+ if (!sky?.mesh?.parent || sky.mesh.visible === false || sky.released) return null;
498
+ range.horizons ??= new WeakMap();
499
+ range.skyColor ??= new THREE.Color();
500
+ const fade = sky.fade;
501
+ const from = horizonOf(sky, fade.from, range);
502
+ range.skyColor.copy(from);
503
+ if (fade.mix > 0) range.skyColor.lerp(horizonOf(sky, fade.to, range), fade.mix);
504
+ return range.skyColor;
505
+ }
506
+
507
+ function horizonOf(sky, index, range) {
508
+ const held = sky.textures.get(index);
509
+ const uniforms = sky.material.uniforms;
510
+ const fallback = index === sky.fade.from ? uniforms.colorFrom.value : uniforms.colorTo.value;
511
+ if (!held?.ready) return fallback;
512
+ if (range.horizons.has(held)) return range.horizons.get(held) ?? fallback;
513
+ let color = null;
514
+ try {
515
+ color = sampleHorizon(ownValue(held.art, 'image'), sky.key.below, range);
516
+ } catch {
517
+ // An unavailable canvas or a tainted image uses the zone's flat colour.
518
+ }
519
+ range.horizons.set(held, color);
520
+ return color ?? fallback;
521
+ }
522
+
523
+ function sampleHorizon(image, below, range) {
524
+ const width = image.naturalWidth || image.width;
525
+ const height = image.naturalHeight || image.height;
526
+ if (!(width > 0 && height > 0) || typeof document === 'undefined') return null;
527
+ const canvas = (range.horizonCanvas ??= document.createElement('canvas'));
528
+ canvas.width = width;
529
+ canvas.height = 1;
530
+ const context = canvas.getContext('2d', { willReadFrequently: true });
531
+ const row = Math.max(0, Math.min(height - 1, Math.round(height * 90 / (90 + below) - 0.5)));
532
+ context.drawImage(image, 0, row, width, 1, 0, 0, width, 1);
533
+ const pixels = context.getImageData(0, 0, width, 1).data;
534
+ // Average the row explicitly: shrinking a wide image to one pixel with
535
+ // canvas interpolation is not guaranteed to include all its bearings.
536
+ // Decode each sRGB pixel before averaging, matching the shader's light.
537
+ const pixel = new THREE.Color();
538
+ let r = 0, g = 0, b = 0;
539
+ for (let i = 0; i < pixels.length; i += 4) {
540
+ pixel.setRGB(pixels[i] / 255, pixels[i + 1] / 255, pixels[i + 2] / 255, THREE.SRGBColorSpace);
541
+ r += pixel.r;
542
+ g += pixel.g;
543
+ b += pixel.b;
544
+ }
545
+ const scale = 4 / pixels.length;
546
+ return pixel.setRGB(r * scale, g * scale, b * scale);
547
+ }