castle-web-cli 0.4.231 → 0.4.233

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (368) hide show
  1. package/dist/agent-failures.d.ts +8 -0
  2. package/dist/agent-failures.js +19 -2
  3. package/dist/agent-prompts.d.ts +1 -1
  4. package/dist/agent-prompts.js +10 -3
  5. package/dist/agent.d.ts +64 -3
  6. package/dist/agent.js +170 -81
  7. package/dist/castle-host/host.d.ts +1 -0
  8. package/dist/castle-host/host.js +51 -3
  9. package/dist/castleJson.d.ts +4 -2
  10. package/dist/castleJson.js +2 -0
  11. package/dist/check.d.ts +3 -1
  12. package/dist/check.js +11 -1
  13. package/dist/devSessionStorage.js +47 -1
  14. package/dist/importPinMismatch.d.ts +22 -0
  15. package/dist/importPinMismatch.js +77 -0
  16. package/dist/importRegression.js +3 -15
  17. package/dist/imports.d.ts +10 -3
  18. package/dist/imports.js +88 -20
  19. package/dist/index.js +5 -4
  20. package/dist/init.js +1 -1
  21. package/dist/platformDoc.js +22 -0
  22. package/dist/routerFences.d.ts +5 -0
  23. package/dist/routerFences.js +12 -2
  24. package/dist/save-deck.d.ts +5 -0
  25. package/dist/save-deck.js +37 -4
  26. package/dist/serve.js +3 -0
  27. package/dist/serverBundle.js +5 -3
  28. package/dist/shell/assets/{index-D2tWM896.js → index-BjOxR-lW.js} +4 -4
  29. package/dist/shell/assets/index-MVLfNYd9.css +1 -0
  30. package/dist/shell/index.html +2 -2
  31. package/dist/taskSteer.d.ts +13 -0
  32. package/dist/taskSteer.js +22 -2
  33. package/kits/base/castle.json +1 -1
  34. package/kits/base/package-lock.json +1 -1
  35. package/kits/base/sdk/README.md +79 -2
  36. package/kits/base/sdk/avatar.d.ts +6 -2
  37. package/kits/base/sdk/avatar.js +12 -4
  38. package/kits/base/sdk/castle.d.ts +1 -1
  39. package/kits/base/sdk/commands.d.ts +14 -0
  40. package/kits/base/sdk/hub.d.ts +6 -2
  41. package/kits/base/sdk/hub.js +13 -0
  42. package/kits/base/sdk/multiplayer.js +17 -1
  43. package/kits/base/sdk/save.js +2 -1
  44. package/kits/base/sdk/server/hub.d.ts +87 -0
  45. package/kits/base/sdk/server/hub.js +70 -0
  46. package/kits/base/sdk/server/platformHandle.d.ts +31 -1
  47. package/kits/base/sdk/server/storage.d.ts +13 -0
  48. package/kits/base/sdk/server/storage.js +46 -0
  49. package/kits/base/sdk/server/wrapper.d.ts +36 -5
  50. package/kits/base/sdk/server/wrapper.js +83 -8
  51. package/kits/hub-game/CLAUDE.md +352 -12
  52. package/kits/hub-game/blueprints/avatar-10.scene +28 -0
  53. package/kits/hub-game/blueprints/avatar-11.scene +28 -0
  54. package/kits/hub-game/blueprints/avatar-12.scene +28 -0
  55. package/kits/hub-game/blueprints/avatar-13.scene +28 -0
  56. package/kits/hub-game/blueprints/avatar-14.scene +28 -0
  57. package/kits/hub-game/blueprints/avatar-15.scene +28 -0
  58. package/kits/hub-game/blueprints/avatar-4.scene +28 -0
  59. package/kits/hub-game/blueprints/avatar-5.scene +28 -0
  60. package/kits/hub-game/blueprints/avatar-6.scene +28 -0
  61. package/kits/hub-game/blueprints/avatar-7.scene +28 -0
  62. package/kits/hub-game/blueprints/avatar-8.scene +28 -0
  63. package/kits/hub-game/blueprints/avatar-9.scene +28 -0
  64. package/kits/hub-game/code/client/actorBudget.js +47 -0
  65. package/kits/hub-game/code/client/attention.js +11 -2
  66. package/kits/hub-game/code/client/avatar.js +345 -32
  67. package/kits/hub-game/code/client/avatarCap.js +228 -0
  68. package/kits/hub-game/code/client/avatarColors.js +70 -0
  69. package/kits/hub-game/code/client/avatarFaces.js +21 -0
  70. package/kits/hub-game/code/client/avatarShare.js +251 -0
  71. package/kits/hub-game/code/client/ballot.js +467 -0
  72. package/kits/hub-game/code/client/build.js +22 -0
  73. package/kits/hub-game/code/client/chat.js +12 -0
  74. package/kits/hub-game/code/client/chrome.js +1334 -50
  75. package/kits/hub-game/code/client/companion.js +716 -0
  76. package/kits/hub-game/code/client/companionDress.js +99 -0
  77. package/kits/hub-game/code/client/decor.js +509 -0
  78. package/kits/hub-game/code/client/earned.js +131 -0
  79. package/kits/hub-game/code/client/emoteBubble.js +75 -0
  80. package/kits/hub-game/code/client/grab.js +363 -20
  81. package/kits/hub-game/code/client/hats.js +26 -0
  82. package/kits/hub-game/code/client/hookLayer.js +328 -15
  83. package/kits/hub-game/code/client/hudClear.js +126 -0
  84. package/kits/hub-game/code/client/idle.js +163 -22
  85. package/kits/hub-game/code/client/interestCap.js +81 -0
  86. package/kits/hub-game/code/client/keys.js +36 -0
  87. package/kits/hub-game/code/client/labelsNear.js +205 -0
  88. package/kits/hub-game/code/client/menuIcons.js +34 -0
  89. package/kits/hub-game/code/client/pack.js +6 -2
  90. package/kits/hub-game/code/client/packFormat.js +3 -3
  91. package/kits/hub-game/code/client/rehello.js +167 -0
  92. package/kits/hub-game/code/client/shot.js +92 -0
  93. package/kits/hub-game/code/client/sound.js +63 -8
  94. package/kits/hub-game/code/client/soundscape.js +1151 -0
  95. package/kits/hub-game/code/client/soundscapeActions.js +99 -0
  96. package/kits/hub-game/code/client/soundscapeAmbience.js +453 -0
  97. package/kits/hub-game/code/client/soundscapeBaked.js +143 -0
  98. package/kits/hub-game/code/client/soundscapeBusker.js +217 -0
  99. package/kits/hub-game/code/client/soundscapeCourt.js +200 -0
  100. package/kits/hub-game/code/client/soundscapeCrowd.js +331 -0
  101. package/kits/hub-game/code/client/soundscapeCues.js +362 -0
  102. package/kits/hub-game/code/client/soundscapeMap.js +181 -0
  103. package/kits/hub-game/code/client/soundscapeMarket.js +176 -0
  104. package/kits/hub-game/code/client/soundscapeMusic.js +126 -0
  105. package/kits/hub-game/code/client/soundscapeMusicEngine.js +460 -0
  106. package/kits/hub-game/code/client/soundscapeSimlish.js +737 -0
  107. package/kits/hub-game/code/client/soundscapeSongs.js +127 -0
  108. package/kits/hub-game/code/client/soundscapeSongsRound3.js +63 -0
  109. package/kits/hub-game/code/client/soundscapeSynthesis.js +168 -0
  110. package/kits/hub-game/code/client/soundscapeUi.js +211 -0
  111. package/kits/hub-game/code/client/soundscapeVoice.js +1209 -0
  112. package/kits/hub-game/code/client/soundscapeWaves.js +206 -0
  113. package/kits/hub-game/code/client/spin.js +101 -0
  114. package/kits/hub-game/code/client/state.js +131 -1
  115. package/kits/hub-game/code/client/stuck.js +259 -0
  116. package/kits/hub-game/code/client/talk.js +538 -47
  117. package/kits/hub-game/code/client/tiers.js +541 -27
  118. package/kits/hub-game/code/client/toastBand.js +37 -0
  119. package/kits/hub-game/code/client/together.js +98 -1
  120. package/kits/hub-game/code/client/visibility.js +43 -0
  121. package/kits/hub-game/code/client/wear.js +470 -97
  122. package/kits/hub-game/code/client/yours.js +199 -0
  123. package/kits/hub-game/code/companionSpec.js +45 -0
  124. package/kits/hub-game/code/privateText.js +7 -0
  125. package/kits/hub-game/code/server/actions.js +133 -0
  126. package/kits/hub-game/code/server/actors.js +14 -1
  127. package/kits/hub-game/code/server/ask.js +155 -0
  128. package/kits/hub-game/code/server/ballot.js +539 -0
  129. package/kits/hub-game/code/server/cells.js +100 -0
  130. package/kits/hub-game/code/server/companion.js +82 -0
  131. package/kits/hub-game/code/server/cues.js +70 -0
  132. package/kits/hub-game/code/server/decor.js +269 -0
  133. package/kits/hub-game/code/server/earned.js +461 -0
  134. package/kits/hub-game/code/server/friendBests.js +166 -0
  135. package/kits/hub-game/code/server/friendsAmong.js +232 -0
  136. package/kits/hub-game/code/server/grab.js +296 -11
  137. package/kits/hub-game/code/server/history.js +5 -0
  138. package/kits/hub-game/code/server/hub.js +1317 -52
  139. package/kits/hub-game/code/server/idle.js +30 -11
  140. package/kits/hub-game/code/server/index.js +2 -2
  141. package/kits/hub-game/code/server/labels.js +28 -2
  142. package/kits/hub-game/code/server/manifest.js +424 -8
  143. package/kits/hub-game/code/server/menu.js +133 -0
  144. package/kits/hub-game/code/server/npcs.js +830 -80
  145. package/kits/hub-game/code/server/party.js +13 -2
  146. package/kits/hub-game/code/server/players.js +22 -0
  147. package/kits/hub-game/code/server/say.js +8 -2
  148. package/kits/hub-game/code/server/shot.js +110 -0
  149. package/kits/hub-game/code/server/standing.js +124 -0
  150. package/kits/hub-game/code/server/vis.js +113 -0
  151. package/kits/hub-game/code/server/wear.js +128 -11
  152. package/kits/hub-game/code/server/yours.js +59 -0
  153. package/kits/hub-game/code/shared/cues.js +9 -0
  154. package/kits/hub-game/code/shared/decor.js +41 -0
  155. package/kits/hub-game/code/shared/shot.js +19 -0
  156. package/kits/hub-game/code/shared/spin.js +57 -0
  157. package/kits/hub-game/code/systems/hub.js +1083 -85
  158. package/kits/hub-game/docs/content-pack.md +1 -1
  159. package/kits/hub-game/docs/contract.md +2440 -61
  160. package/kits/hub-game/docs/home-pieces.md +64 -0
  161. package/kits/hub-game/models/avatar-10.pxmodel +28 -0
  162. package/kits/hub-game/models/avatar-11.pxmodel +28 -0
  163. package/kits/hub-game/models/avatar-12.pxmodel +27 -0
  164. package/kits/hub-game/models/avatar-13.pxmodel +24 -0
  165. package/kits/hub-game/models/avatar-14.pxmodel +29 -0
  166. package/kits/hub-game/models/avatar-15.pxmodel +24 -0
  167. package/kits/hub-game/models/avatar-4.pxmodel +29 -0
  168. package/kits/hub-game/models/avatar-5.pxmodel +27 -0
  169. package/kits/hub-game/models/avatar-6.pxmodel +26 -0
  170. package/kits/hub-game/models/avatar-7.pxmodel +25 -0
  171. package/kits/hub-game/models/avatar-8.pxmodel +24 -0
  172. package/kits/hub-game/models/avatar-9.pxmodel +30 -0
  173. package/kits/hub-game/models/earned/badge-round.pxmodel +100 -0
  174. package/kits/hub-game/models/earned/badge-shield.pxmodel +117 -0
  175. package/kits/hub-game/models/earned/badge-star.pxmodel +87 -0
  176. package/kits/hub-game/models/earned/belt-plain.pxmodel +72 -0
  177. package/kits/hub-game/models/earned/held-ball.pxmodel +43 -0
  178. package/kits/hub-game/models/earned/held-lantern.pxmodel +85 -0
  179. package/kits/hub-game/models/earned/held-net.pxmodel +57 -0
  180. package/kits/hub-game/models/earned/held-trophy.pxmodel +109 -0
  181. package/kits/hub-game/models/earned/pin-round.pxmodel +62 -0
  182. package/kits/hub-game/models/earned/sash-plain.pxmodel +66 -0
  183. package/kits/hub-game/models/earned/square/belt-plain.pxmodel +104 -0
  184. package/kits/hub-game/models/earned/square/sash-plain.pxmodel +98 -0
  185. package/kits/hub-game/models/hats/bat-clip.pxmodel +206 -0
  186. package/kits/hub-game/models/hats/beekeeper.pxmodel +149 -0
  187. package/kits/hub-game/models/hats/cap.pxmodel +162 -0
  188. package/kits/hub-game/models/hats/captain.pxmodel +178 -0
  189. package/kits/hub-game/models/hats/crooked-top.pxmodel +172 -0
  190. package/kits/hub-game/models/hats/flower-crown.pxmodel +451 -0
  191. package/kits/hub-game/models/hats/foam-crown.pxmodel +179 -0
  192. package/kits/hub-game/models/hats/lantern.pxmodel +230 -0
  193. package/kits/hub-game/models/hats/laurel.pxmodel +533 -0
  194. package/kits/hub-game/models/hats/lighthouse.pxmodel +96 -0
  195. package/kits/hub-game/models/hats/sailor.pxmodel +141 -0
  196. package/kits/hub-game/models/hats/souwester.pxmodel +131 -0
  197. package/kits/hub-game/models/hats/straw.pxmodel +139 -0
  198. package/kits/hub-game/models/hats/sunflower.pxmodel +406 -0
  199. package/kits/hub-game/models/hats/sweatband.pxmodel +112 -0
  200. package/kits/hub-game/models/hats/witch.pxmodel +147 -0
  201. package/kits/hub-game/package-lock.json +2 -0
  202. package/kits/hub-game/package.json +2 -1
  203. package/kits/hub-game/scripts/check.mjs +78 -11
  204. package/kits/hub-game/scripts/companion-follower-wire.json +1 -0
  205. package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +121 -0
  206. package/kits/hub-game/scripts/fixtures/decor-keyless.json +293 -0
  207. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +23 -0
  208. package/kits/hub-game/scripts/fixtures/fake-dom.mjs +107 -0
  209. package/kits/hub-game/scripts/fixtures/interest-legacy.json +385 -0
  210. package/kits/hub-game/scripts/fixtures/npc-notes-v1.77.jsonl +4 -0
  211. package/kits/hub-game/scripts/fixtures/vis-shared-wire.json +1 -0
  212. package/kits/hub-game/scripts/gen-avatars.mjs +933 -16
  213. package/kits/hub-game/scripts/gen-earned.mjs +285 -0
  214. package/kits/hub-game/scripts/gen-hats.mjs +827 -0
  215. package/kits/hub-game/scripts/grab.before-orbit.mjs +400 -0
  216. package/kits/hub-game/scripts/soundscape-wave-analysis.mjs +125 -0
  217. package/kits/hub-game/scripts/test-actions-client.mjs +488 -0
  218. package/kits/hub-game/scripts/test-actions.mjs +298 -0
  219. package/kits/hub-game/scripts/test-actor-budget.mjs +44 -0
  220. package/kits/hub-game/scripts/test-actors.mjs +19 -17
  221. package/kits/hub-game/scripts/test-ask-client.mjs +358 -0
  222. package/kits/hub-game/scripts/test-ask.mjs +269 -0
  223. package/kits/hub-game/scripts/test-attention.mjs +10 -1
  224. package/kits/hub-game/scripts/test-avatar-cap.mjs +379 -0
  225. package/kits/hub-game/scripts/test-avatar-colors.mjs +72 -0
  226. package/kits/hub-game/scripts/test-avatar-models.mjs +181 -0
  227. package/kits/hub-game/scripts/test-avatar-share.mjs +318 -0
  228. package/kits/hub-game/scripts/test-avatar-wire.mjs +753 -0
  229. package/kits/hub-game/scripts/test-avatar.mjs +540 -7
  230. package/kits/hub-game/scripts/test-ballot.mjs +1001 -0
  231. package/kits/hub-game/scripts/test-build.mjs +31 -0
  232. package/kits/hub-game/scripts/test-cells.mjs +71 -0
  233. package/kits/hub-game/scripts/test-chat.mjs +694 -0
  234. package/kits/hub-game/scripts/test-classic.mjs +2 -0
  235. package/kits/hub-game/scripts/test-companion-chat.mjs +198 -0
  236. package/kits/hub-game/scripts/test-companion-client.mjs +1167 -0
  237. package/kits/hub-game/scripts/test-companion.mjs +259 -0
  238. package/kits/hub-game/scripts/test-decor-client.mjs +303 -0
  239. package/kits/hub-game/scripts/test-decor.mjs +457 -0
  240. package/kits/hub-game/scripts/test-earned-client.mjs +459 -0
  241. package/kits/hub-game/scripts/test-earned.mjs +1194 -0
  242. package/kits/hub-game/scripts/test-emote-bubble.mjs +110 -0
  243. package/kits/hub-game/scripts/test-friend-bests.mjs +435 -0
  244. package/kits/hub-game/scripts/test-grab-client.mjs +186 -3
  245. package/kits/hub-game/scripts/test-grab-orbit.mjs +918 -0
  246. package/kits/hub-game/scripts/test-grab.mjs +864 -3
  247. package/kits/hub-game/scripts/test-hats.mjs +483 -0
  248. package/kits/hub-game/scripts/test-hub-leaving.mjs +203 -0
  249. package/kits/hub-game/scripts/test-hub-ops.mjs +439 -2
  250. package/kits/hub-game/scripts/test-hub-trip.mjs +1228 -1
  251. package/kits/hub-game/scripts/test-hud-clear.mjs +1000 -0
  252. package/kits/hub-game/scripts/test-idle.mjs +361 -1
  253. package/kits/hub-game/scripts/test-interest-cap.mjs +36 -0
  254. package/kits/hub-game/scripts/test-interest-cells.mjs +493 -0
  255. package/kits/hub-game/scripts/test-interest-client.mjs +118 -0
  256. package/kits/hub-game/scripts/test-keys.mjs +46 -1
  257. package/kits/hub-game/scripts/test-labels.mjs +596 -0
  258. package/kits/hub-game/scripts/test-manifest.mjs +282 -0
  259. package/kits/hub-game/scripts/test-menu-client.mjs +480 -0
  260. package/kits/hub-game/scripts/test-menu.mjs +296 -0
  261. package/kits/hub-game/scripts/test-npcs.mjs +1718 -12
  262. package/kits/hub-game/scripts/test-object-entry.mjs +76 -0
  263. package/kits/hub-game/scripts/test-pack.mjs +7 -0
  264. package/kits/hub-game/scripts/test-party.mjs +22 -1
  265. package/kits/hub-game/scripts/test-picker.mjs +314 -0
  266. package/kits/hub-game/scripts/test-rehello.mjs +1039 -0
  267. package/kits/hub-game/scripts/test-relations-among.mjs +222 -0
  268. package/kits/hub-game/scripts/test-relations-refresh.mjs +188 -0
  269. package/kits/hub-game/scripts/test-say.mjs +59 -2
  270. package/kits/hub-game/scripts/test-shot.mjs +756 -0
  271. package/kits/hub-game/scripts/test-soundscape.mjs +5432 -0
  272. package/kits/hub-game/scripts/test-spin.mjs +314 -0
  273. package/kits/hub-game/scripts/test-standing.mjs +416 -0
  274. package/kits/hub-game/scripts/test-stuck.mjs +1903 -0
  275. package/kits/hub-game/scripts/test-tier-cells.mjs +706 -0
  276. package/kits/hub-game/scripts/test-tiers-render.mjs +339 -0
  277. package/kits/hub-game/scripts/test-tiers.mjs +666 -3
  278. package/kits/hub-game/scripts/test-toast-band.mjs +61 -0
  279. package/kits/hub-game/scripts/test-try-on.mjs +940 -0
  280. package/kits/hub-game/scripts/test-vis.mjs +343 -0
  281. package/kits/hub-game/scripts/test-visibility.mjs +134 -0
  282. package/kits/hub-game/scripts/test-yours-chrome.mjs +166 -0
  283. package/kits/hub-game/scripts/test-yours.mjs +372 -0
  284. package/kits/multiplayer-3d/CLAUDE.md +50 -0
  285. package/kits/multiplayer-3d/castle.json +5 -5
  286. package/kits/multiplayer-3d/code/client/avatars.js +7 -0
  287. package/kits/multiplayer-3d/code/client/gait.js +65 -0
  288. package/kits/multiplayer-3d/code/client/nameTags.js +59 -4
  289. package/kits/multiplayer-3d/code/options.js +5 -0
  290. package/kits/multiplayer-3d/code/server/ownership.js +10 -2
  291. package/kits/multiplayer-3d/code/server/sceneBodies.js +12 -0
  292. package/kits/multiplayer-3d/code/server/world.js +7 -0
  293. package/kits/multiplayer-3d/code/systems/multiplayer.js +74 -4
  294. package/kits/multiplayer-3d/package.json +2 -1
  295. package/kits/multiplayer-3d/scripts/fixtures/README.md +11 -0
  296. package/kits/multiplayer-3d/scripts/fixtures/ownership-legacy.json +2 -0
  297. package/kits/multiplayer-3d/scripts/ownership-harness.mjs +102 -0
  298. package/kits/multiplayer-3d/scripts/ownership-loader.mjs +46 -0
  299. package/kits/multiplayer-3d/scripts/ownership-worker.mjs +15 -0
  300. package/kits/multiplayer-3d/scripts/record-ownership-session.mjs +98 -0
  301. package/kits/multiplayer-3d/scripts/test-eligible-claims.mjs +167 -0
  302. package/kits/multiplayer-3d/scripts/test-own-name-tag.mjs +247 -0
  303. package/kits/physics-2d/CLAUDE.md +9 -0
  304. package/kits/physics-2d/castle.json +2 -2
  305. package/kits/physics-2d/engine/scene.js +288 -1
  306. package/kits/physics-2d/engine/skyKey.js +129 -0
  307. package/kits/physics-2d/engine/stillClock.js +106 -0
  308. package/kits/physics-2d/engine/updateBudget.js +21 -0
  309. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +370 -1
  310. package/kits/physics-3d/CLAUDE.md +1391 -0
  311. package/kits/physics-3d/behaviors/Player.jsx +921 -3
  312. package/kits/physics-3d/castle.json +3 -3
  313. package/kits/physics-3d/docs/pxmodel-format.md +12 -0
  314. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +98 -10
  315. package/kits/physics-3d/engine3d/actornode.js +86 -0
  316. package/kits/physics-3d/engine3d/animationBudget.js +23 -0
  317. package/kits/physics-3d/engine3d/editorWorld.js +6 -0
  318. package/kits/physics-3d/engine3d/emptynodes.js +232 -0
  319. package/kits/physics-3d/engine3d/framecap.js +96 -0
  320. package/kits/physics-3d/engine3d/gait.js +118 -0
  321. package/kits/physics-3d/engine3d/kithooks.js +47 -0
  322. package/kits/physics-3d/engine3d/look.js +507 -48
  323. package/kits/physics-3d/engine3d/lookbake.js +208 -0
  324. package/kits/physics-3d/engine3d/materialpresets.js +2 -0
  325. package/kits/physics-3d/engine3d/motion.js +39 -10
  326. package/kits/physics-3d/engine3d/nearshadows.js +37 -19
  327. package/kits/physics-3d/engine3d/optimize.js +58 -5
  328. package/kits/physics-3d/engine3d/orbitinput.js +755 -0
  329. package/kits/physics-3d/engine3d/orbitlens.js +48 -0
  330. package/kits/physics-3d/engine3d/ownmodel.js +213 -0
  331. package/kits/physics-3d/engine3d/pxmodel.js +42 -11
  332. package/kits/physics-3d/engine3d/shadowfade.js +882 -0
  333. package/kits/physics-3d/engine3d/sky.js +547 -0
  334. package/kits/physics-3d/engine3d/skylife.js +306 -0
  335. package/kits/physics-3d/engine3d/unchanged.js +11 -0
  336. package/kits/physics-3d/engine3d/viewrange.js +52 -0
  337. package/kits/physics-3d/engine3d/world3d.js +870 -87
  338. package/kits/physics-3d/main.jsx +5 -0
  339. package/kits/physics-3d/package.json +1 -1
  340. package/kits/physics-3d/scripts/Player.before-orbit.mjs +310 -0
  341. package/kits/physics-3d/scripts/Scene3DPlayer.before-orbit.jsx +337 -0
  342. package/kits/physics-3d/scripts/look-baseline.mjs +155 -0
  343. package/kits/physics-3d/scripts/test-camera-follow.mjs +12 -2
  344. package/kits/physics-3d/scripts/test-camera-orbit.mjs +4588 -0
  345. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +787 -0
  346. package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +435 -0
  347. package/kits/physics-3d/scripts/test-frame-cap.mjs +452 -0
  348. package/kits/physics-3d/scripts/test-gait.mjs +387 -0
  349. package/kits/physics-3d/scripts/test-look-bake.mjs +1056 -0
  350. package/kits/physics-3d/scripts/test-model-parse-cache.mjs +92 -0
  351. package/kits/physics-3d/scripts/test-near-shadows.mjs +3 -0
  352. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +1920 -0
  353. package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +545 -0
  354. package/kits/physics-3d/scripts/test-orbit-shot.mjs +583 -0
  355. package/kits/physics-3d/scripts/test-orbit-view.mjs +230 -0
  356. package/kits/physics-3d/scripts/test-skip-empty-nodes.mjs +845 -0
  357. package/kits/physics-3d/scripts/test-sky.mjs +2470 -0
  358. package/kits/physics-3d/scripts/test-static-actors.mjs +13 -1
  359. package/kits/physics-3d/scripts/test-static-passes.mjs +1 -1
  360. package/kits/physics-3d/scripts/test-static-scenery.mjs +2171 -0
  361. package/kits/physics-3d/scripts/test-steady-hover.mjs +635 -0
  362. package/kits/physics-3d/scripts/test-view-range.mjs +260 -0
  363. package/kits/physics-3d/systems/physics3d.js +474 -12
  364. package/kits/real-time/castle.json +2 -2
  365. package/kits/real-time/code/server/gameHooks.js +7 -0
  366. package/kits/real-time/code/server/session.js +97 -19
  367. package/package.json +2 -2
  368. package/dist/shell/assets/index-Cf61cNfT.css +0 -1
@@ -0,0 +1,755 @@
1
+ // Pointer, wheel and right-button input for a scene that set `"engine": {
2
+ // "camera": { "follow": "rigid", "control": "orbit" } }` (the kit's CLAUDE.md
3
+ // has the terms): the player turns, tilts and zooms the Player's camera.
4
+ // Scene3DPlayer's `attachInput` makes this the first time a pointer goes down
5
+ // under the key, Shift is pressed there, or a Player runs under it (`runtime.orbitInput()`), hands
6
+ // each pointer that goes down under the key to it, and leaves every other one
7
+ // to the handlers it always had. A runtime that never meets the key never
8
+ // makes it.
9
+ //
10
+ // - touch and pen: a drag that starts in the left half of the canvas is the
11
+ // movement stick (`runtime.moveInput`, as without the key); one that starts
12
+ // in the right half turns and tilts the camera; two fingers that both
13
+ // landed in the right half are a pinch, which zooms. The left half is the
14
+ // stick's: a finger that lands there is never part of a pinch.
15
+ // - mouse: a drag with any button turns and tilts; the wheel zooms. On a
16
+ // desktop the drag holds the pointer lock (Roblox's right-drag): a right
17
+ // press asks for it at once, any other button once the drag passes the
18
+ // tap slop, so a click is never locked. While locked the turn comes from
19
+ // movementX/Y; the lock ends with the drag (the last button up, a blur,
20
+ // the page hidden, a scene load, detach), and when the browser ends it
21
+ // (Escape, the host taking focus) the drag ends with no tap. Where the
22
+ // lock is missing or refused the drag goes on as before, on the pointer
23
+ // capture taken at the press (see `attachOrbitInput`).
24
+ // Shift or the desktop lock button keeps the lock until toggled off,
25
+ // Escape, blur, page hidden or a scene load. Then every mouse move turns,
26
+ // with no button needed; a quick left click still jumps.
27
+ // - a short tap that did not move is a jump, as without the key (a mouse's
28
+ // left button only).
29
+ //
30
+ // What the camera is asked for is added up on `runtime.lookInput` until the
31
+ // Player takes it (`consume`), once a frame.
32
+
33
+ // Radians of turn or tilt per CSS pixel dragged.
34
+ export const LOOK_RAD_PER_PX = 0.006;
35
+ // One notch of a mouse wheel moves the camera this much nearer or farther.
36
+ export const WHEEL_ZOOM_PER_NOTCH = 1.1;
37
+ const WHEEL_NOTCH_PX = 100;
38
+ // A wheel that reports lines: a notch is three of them.
39
+ const WHEEL_LINE_PX = WHEEL_NOTCH_PX / 3;
40
+ // The most one wheel event zooms (a flung trackpad reports hundreds of px).
41
+ const WHEEL_ZOOM_MOST = 1.5;
42
+ // Fingers closer than this count as this far apart, so a pinch that closes
43
+ // to nothing does not zoom without bound.
44
+ const PINCH_NEAREST_PX = 24;
45
+ // What is asked for and not yet taken stays within this.
46
+ const ZOOM_PENDING_MOST = 16;
47
+
48
+ const within = (value, least, most) => Math.max(least, Math.min(most, value));
49
+
50
+ // The stick a drag of (dx, dy) pixels holds: that over `radius`, no longer
51
+ // than 1.
52
+ export function stickFrom(dx, dy, radius) {
53
+ const len = Math.hypot(dx, dy) / radius;
54
+ const scale = len > 1 ? 1 / (len * radius) : 1 / radius;
55
+ return { x: dx * scale, y: dy * scale };
56
+ }
57
+
58
+ // The pointers that are down and what each is doing (its role):
59
+ // 'tap' down, not yet moved past the slop
60
+ // 'stick' holds the movement stick
61
+ // 'look' turns and tilts the camera
62
+ // 'pinch' one of the two fingers zooming
63
+ // 'spent' nothing more until it lifts (the finger left over from a pinch,
64
+ // a second drag in the left half, a drag begun in the right half
65
+ // while two fingers pinch)
66
+ // No DOM here: `down`, `move`, `up` and `wheel` are handed plain numbers, so
67
+ // the roles can be tested. `stick` is `runtime.moveInput`'s object, `onTap`
68
+ // is called for a jump, `tuning` is attachInput's { stickRadius, tapSlop,
69
+ // tapMs }.
70
+ export function makeLookGestures(stick, onTap, tuning) {
71
+ const pointers = new Map();
72
+ let stickId = null;
73
+ let locked = false;
74
+ const asked = { yaw: 0, pitch: 0, zoom: 1 };
75
+ const taken = { yaw: 0, pitch: 0, zoom: 1, locked: false };
76
+ const holding = (role) => [...pointers.values()].filter((p) => p.role === role);
77
+ const letGoOfStick = () => {
78
+ stickId = null;
79
+ stick.active = false;
80
+ stick.x = 0;
81
+ stick.y = 0;
82
+ };
83
+ const drop = () => {
84
+ asked.yaw = 0;
85
+ asked.pitch = 0;
86
+ asked.zoom = 1;
87
+ };
88
+
89
+ // What `runtime.lookInput` is: the turn and tilt (radians) and the zoom (a
90
+ // factor on the camera's distance; under 1 is nearer) asked for since they
91
+ // were last taken.
92
+ const look = {
93
+ // Takes what was asked for. The object returned is the same one each
94
+ // time. After `lock` it takes nothing: what was asked is dropped, and
95
+ // `locked` says the camera is not the player's this frame.
96
+ consume() {
97
+ taken.locked = locked;
98
+ taken.yaw = locked ? 0 : asked.yaw;
99
+ taken.pitch = locked ? 0 : asked.pitch;
100
+ taken.zoom = locked ? 1 : asked.zoom;
101
+ locked = false;
102
+ drop();
103
+ return taken;
104
+ },
105
+ // The next `consume` takes nothing (the hub during a door trip: its
106
+ // camera, not the player's). Called again each frame it should hold.
107
+ lock() {
108
+ locked = true;
109
+ },
110
+ };
111
+
112
+ // What a pointer that has just moved past the slop becomes.
113
+ const roleOnDrag = (p) => {
114
+ if (p.mouse) return 'look';
115
+ if (p.left) return stickId === null ? 'stick' : 'spent';
116
+ return holding('pinch').length > 0 ? 'spent' : 'look';
117
+ };
118
+
119
+ const zoomBy = (factor) => {
120
+ asked.zoom = within(asked.zoom * factor, 1 / ZOOM_PENDING_MOST, ZOOM_PENDING_MOST);
121
+ };
122
+
123
+ const apart = (a, b) => Math.max(PINCH_NEAREST_PX, Math.hypot(a.x - b.x, a.y - b.y));
124
+
125
+ const gestures = {
126
+ // Whether any pointer is down here.
127
+ busy: false,
128
+ look,
129
+ roleOf: (id) => pointers.get(id)?.role ?? null,
130
+
131
+ // A mouse move under shift lock needs no held pointer or tap slop.
132
+ turn(dx, dy) {
133
+ asked.yaw += (Number.isFinite(dx) ? dx : 0) * LOOK_RAD_PER_PX;
134
+ asked.pitch += (Number.isFinite(dy) ? dy : 0) * LOOK_RAD_PER_PX;
135
+ },
136
+
137
+ // `at` is { x, y, time, mouse, button, left }: where (CSS px), when (ms),
138
+ // whether it is a mouse and which button, and whether it is in the left
139
+ // half of the canvas.
140
+ down(id, at) {
141
+ const p = { x0: at.x, y0: at.y, x: at.x, y: at.y, time: at.time, moved: false, role: 'tap', mouse: at.mouse === true, button: at.button ?? 0, left: at.left === true };
142
+ if (!p.mouse && !p.left && holding('pinch').length === 0) {
143
+ // A second finger in the right half, beside one that landed there
144
+ // and is still a tap or turning the camera: a pinch. A finger in the
145
+ // left half is the stick's and is left out of it, on either side.
146
+ const others = [...pointers.values()].filter((o) => !o.mouse && !o.left && (o.role === 'tap' || o.role === 'look'));
147
+ if (others.length === 1) {
148
+ others[0].role = 'pinch';
149
+ p.role = 'pinch';
150
+ }
151
+ }
152
+ pointers.set(id, p);
153
+ gestures.busy = true;
154
+ },
155
+
156
+ // Returns whether the pointer is one that went down here.
157
+ move(id, x, y) {
158
+ const p = pointers.get(id);
159
+ if (!p) return false;
160
+ const from = { x: p.x, y: p.y };
161
+ if (!p.moved && Math.hypot(x - p.x0, y - p.y0) > tuning.tapSlop) {
162
+ p.moved = true;
163
+ if (p.role === 'tap') p.role = roleOnDrag(p);
164
+ if (p.role === 'stick') stickId = id;
165
+ }
166
+ if (p.role === 'pinch') {
167
+ const other = holding('pinch').find((o) => o !== p);
168
+ const before = other ? apart(from, other) : 0;
169
+ p.x = x;
170
+ p.y = y;
171
+ // Fingers moving apart bring the camera nearer.
172
+ if (other) zoomBy(before / apart(p, other));
173
+ return true;
174
+ }
175
+ p.x = x;
176
+ p.y = y;
177
+ if (p.role === 'stick') {
178
+ Object.assign(stick, stickFrom(x - p.x0, y - p.y0, tuning.stickRadius));
179
+ stick.active = true;
180
+ } else if (p.role === 'look') {
181
+ // Dragging right swings the view right; dragging up looks up.
182
+ asked.yaw += (x - from.x) * LOOK_RAD_PER_PX;
183
+ asked.pitch += (y - from.y) * LOOK_RAD_PER_PX;
184
+ }
185
+ return true;
186
+ },
187
+
188
+ // A pointer lifted, or cancelled (no tap then). Returns whether it is one
189
+ // that went down here.
190
+ up(id, time, cancelled) {
191
+ const p = pointers.get(id);
192
+ if (!p) return false;
193
+ pointers.delete(id);
194
+ gestures.busy = pointers.size > 0;
195
+ if (stickId === id) letGoOfStick();
196
+ // The finger left from a pinch neither turns the camera nor walks.
197
+ if (p.role === 'pinch') for (const other of holding('pinch')) other.role = 'spent';
198
+ // Only a finger that is still a tap jumps: never one of a pinch, nor
199
+ // one left spent.
200
+ const tapped = !cancelled && p.role === 'tap' && !p.moved && time - p.time < tuning.tapMs;
201
+ if (tapped && (!p.mouse || p.button === 0)) onTap();
202
+ return true;
203
+ },
204
+
205
+ // Every pointer is let go of at once, with no tap: the stick if one of
206
+ // them held it, what was asked of the camera and not yet taken, and a
207
+ // lock. For a scene load.
208
+ cancel() {
209
+ pointers.clear();
210
+ gestures.busy = false;
211
+ if (stickId !== null) letGoOfStick();
212
+ locked = false;
213
+ drop();
214
+ },
215
+
216
+ // A mouse drag made a look at once (a second button pressed while it
217
+ // was still a tap): it will not jump.
218
+ drag(id) {
219
+ const p = pointers.get(id);
220
+ if (!p || !p.mouse || p.role !== 'tap') return;
221
+ p.moved = true;
222
+ p.role = 'look';
223
+ },
224
+
225
+ // A wheel event's deltaY and deltaMode: away from the player is nearer.
226
+ wheel(deltaY, deltaMode) {
227
+ const px = deltaY * (deltaMode === 1 ? WHEEL_LINE_PX : deltaMode === 2 ? WHEEL_NOTCH_PX : 1);
228
+ if (!Number.isFinite(px) || px === 0) return;
229
+ zoomBy(within(WHEEL_ZOOM_PER_NOTCH ** (px / WHEEL_NOTCH_PX), 1 / WHEEL_ZOOM_MOST, WHEEL_ZOOM_MOST));
230
+ },
231
+ };
232
+ return gestures;
233
+ }
234
+
235
+ // The look inputs this file made, so the engine acts on its own input only
236
+ // (`isOrbitLook`): something else on `runtime.lookInput` is left alone.
237
+ const ours = new WeakSet();
238
+ export const isOrbitLook = (look) => ours.has(look);
239
+
240
+ // The gestures on a canvas; this sets `runtime.lookInput`. The wheel and
241
+ // context-menu listeners are added by `runtime.lookInput.listen()`, which the
242
+ // Player calls every frame it runs under the key, and taken off by
243
+ // `runtime.lookInput.reset()`, which the physics system calls on every scene
244
+ // load and on dispose (`Physics3DSystem.reset`), with every pointer let go of
245
+ // (`cancel`). A tap already handed to attachInput and not yet taken stays
246
+ // with it across the load, as it does without the key. So from the first
247
+ // frame of a scene without the key there is no
248
+ // pointer, listener or pending look here, and a pointer held across any load
249
+ // does nothing more until it lifts: the handlers attachInput always had do
250
+ // not know it either.
251
+ //
252
+ // `onLost`, when given, is the canvas's own pointerup handler, for a
253
+ // pointer whose capture a lock of ours took (Scene3DPlayer passes its own,
254
+ // so a keyless pointer goes through the keyless path). It is handed the
255
+ // pointer's real pointerup or pointercancel when that lands beyond the
256
+ // canvas while the lock (or our request, or our exit) is on, and a made-up
257
+ // pointercancel for one whose lift was never seen at all. Without it these
258
+ // go to this input's own `up`.
259
+ export function attachOrbitInput(canvas, runtime, stick, onTap, tuning, onLost) {
260
+ const gestures = makeLookGestures(stick, onTap, tuning);
261
+ const lift = (event) => {
262
+ if (onLost) onLost(event);
263
+ else input.up(event);
264
+ };
265
+ let control;
266
+ const lock = makeMouseLock(canvas, gestures, lift, () => control.update());
267
+ control = makeShiftLockControl(canvas, runtime, lock, () => input.shiftLock.toggle());
268
+ let listening = false;
269
+ const onWheel = (event) => {
270
+ event.preventDefault();
271
+ gestures.wheel(event.deltaY, event.deltaMode);
272
+ };
273
+ const onContextMenu = (event) => event.preventDefault();
274
+ const unlisten = () => {
275
+ if (!listening) return;
276
+ listening = false;
277
+ canvas.removeEventListener('wheel', onWheel);
278
+ canvas.removeEventListener('contextmenu', onContextMenu);
279
+ };
280
+ gestures.look.listen = () => {
281
+ if (runtime.cameraControl !== 'orbit') return;
282
+ control.show();
283
+ if (listening) return;
284
+ listening = true;
285
+ canvas.addEventListener('wheel', onWheel, { passive: false });
286
+ canvas.addEventListener('contextmenu', onContextMenu);
287
+ };
288
+ gestures.look.reset = () => {
289
+ gestures.cancel();
290
+ lock.drop();
291
+ unlisten();
292
+ control.hide();
293
+ };
294
+ ours.add(gestures.look);
295
+ runtime.lookInput = gestures.look;
296
+ const input = {
297
+ shiftLock: {
298
+ get active() {
299
+ return lock.shiftLock.active;
300
+ },
301
+ toggle() {
302
+ if (runtime.cameraControl !== 'orbit') return;
303
+ control.show();
304
+ lock.shiftLock.toggle(control.available());
305
+ },
306
+ },
307
+ // Moves also belong here with no held pointer while shift lock is on.
308
+ get active() {
309
+ return gestures.busy || lock.shiftLock.active;
310
+ },
311
+ // Whether a pointer that went down under the key is still down: its
312
+ // lift is this file's.
313
+ get busy() {
314
+ return gestures.busy;
315
+ },
316
+ down(event) {
317
+ canvas.focus();
318
+ const rect = canvas.getBoundingClientRect();
319
+ gestures.down(event.pointerId, {
320
+ x: event.clientX,
321
+ y: event.clientY,
322
+ time: performance.now(),
323
+ mouse: event.pointerType === 'mouse',
324
+ button: event.button,
325
+ left: event.clientX - rect.left < rect.width / 2,
326
+ });
327
+ // Under a lock a capture cannot be taken (InvalidStateError); the
328
+ // lock's end gives it (`lock.held`).
329
+ lock.held(event.pointerId, true);
330
+ lock.capture(event.pointerId);
331
+ lock.down(event);
332
+ },
333
+ move: (event) => lock.move(event) ?? gestures.move(event.pointerId, event.clientX, event.clientY),
334
+ up: (event) => {
335
+ const ours = gestures.up(event.pointerId, performance.now(), event.type === 'pointercancel');
336
+ lock.held(event.pointerId, false);
337
+ lock.up(event);
338
+ return ours;
339
+ },
340
+ // A pointer that went down or up on the canvas without the key
341
+ // (Scene3DPlayer's own handlers, in a runtime that has met the key): it
342
+ // is held, and gets its capture back when a lock of ours ends.
343
+ pointer: (event) => lock.held(event.pointerId, event.type === 'pointerdown'),
344
+ detach: () => {
345
+ gestures.cancel();
346
+ lock.drop();
347
+ unlisten();
348
+ control.detach();
349
+ },
350
+ };
351
+ return input;
352
+ }
353
+
354
+ // Made only by an orbit input, and its DOM only on a keyed desktop frame or toggle.
355
+ // It lives beside the canvas so it never enters the canvas's pointer path.
356
+ function makeShiftLockControl(canvas, runtime, lock, toggle) {
357
+ const doc = canvas.ownerDocument;
358
+ let media;
359
+ let button = null;
360
+ const available = () => {
361
+ if (typeof canvas.requestPointerLock !== 'function' || typeof doc?.exitPointerLock !== 'function') return false;
362
+ media ??= doc.defaultView?.matchMedia?.('(hover: hover) and (pointer: fine)');
363
+ return media?.matches === true;
364
+ };
365
+ const update = () => {
366
+ if (button === null) return;
367
+ button.setAttribute('aria-pressed', String(lock.shiftLock.active));
368
+ button.style.color = lock.shiftLock.active ? '#7bd9ed' : '#e6e6e2';
369
+ button.style.background = lock.shiftLock.active ? 'rgba(32, 66, 74, 0.8)' : 'rgba(0, 0, 0, 0.45)';
370
+ };
371
+ const onDown = (event) => {
372
+ event.stopPropagation();
373
+ event.preventDefault();
374
+ };
375
+ const onClick = (event) => {
376
+ event.stopPropagation();
377
+ canvas.focus();
378
+ toggle();
379
+ };
380
+ return {
381
+ available,
382
+ update,
383
+ show() {
384
+ const visible = runtime.cameraControl === 'orbit' && available();
385
+ if (visible && button === null && canvas.parentElement) {
386
+ button = doc.createElement('button');
387
+ button.type = 'button';
388
+ button.title = 'Shift lock (Shift)';
389
+ button.setAttribute('aria-label', button.title);
390
+ button.innerHTML = '<svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" aria-hidden="true"><rect x="5" y="10" width="14" height="11" rx="3"/><path d="M8 10V7a4 4 0 0 1 8 0v3"/><path d="M12 14v3"/></svg>';
391
+ Object.assign(button.style, {
392
+ position: 'absolute', right: '16px', bottom: '16px', width: '44px', height: '44px',
393
+ border: '1px solid rgba(230, 230, 226, 0.3)', borderRadius: '10px', padding: '0',
394
+ alignItems: 'center', justifyContent: 'center', cursor: 'pointer', zIndex: '1',
395
+ touchAction: 'none',
396
+ });
397
+ button.addEventListener('pointerdown', onDown);
398
+ button.addEventListener('click', onClick);
399
+ canvas.parentElement.appendChild(button);
400
+ update();
401
+ }
402
+ // Called every keyed frame: the style is written only when it changes.
403
+ const display = visible ? 'flex' : 'none';
404
+ if (button !== null && button.style.display !== display) button.style.display = display;
405
+ },
406
+ hide() {
407
+ if (button !== null && button.style.display !== 'none') button.style.display = 'none';
408
+ },
409
+ detach() {
410
+ if (button === null) return;
411
+ button.removeEventListener('pointerdown', onDown);
412
+ button.removeEventListener('click', onClick);
413
+ button.remove();
414
+ button = null;
415
+ },
416
+ };
417
+ }
418
+
419
+ // The pointer lock a desktop mouse look-drag or shift lock holds under the key (only
420
+ // `pointerType === 'mouse'`; touch and pen never come here).
421
+ // Shift lock owns it from its toggle gesture until turned off or cancelled;
422
+ // the drag path never asks for it or releases it while that owner is on.
423
+ //
424
+ // - asked for: on a right-button press at once; for any other button once
425
+ // the drag passes the tap slop (it is a look then), or when a second
426
+ // button is pressed while it is still a tap. So a left tap still jumps
427
+ // and a click is never locked. At most once per drag.
428
+ // - while locked, the turn comes from movementX/Y at LOOK_RAD_PER_PX (the
429
+ // pointer's client position stands still under a lock); before it lands,
430
+ // and without it, from clientX/Y as always.
431
+ // - let go of (exitPointerLock): on the drag's pointerup (pointer events
432
+ // send it when the last button is up), a pointermove with no button
433
+ // down (a lost pointerup), the window's blur, the page hidden, a scene
434
+ // load (`reset`) and detach. The browser puts the cursor back where the
435
+ // lock began.
436
+ // - ended by the browser (Escape, the host page taking focus): the drag is
437
+ // let go of, no tap, so no look or stick is left held.
438
+ // - a lock of ours that lands when no drag wants it (the button came up
439
+ // first, the next press is still a tap, a scene load came between) is
440
+ // let go of as soon as it is known.
441
+ // - a lock that lands takes the capture of every pointer down on the
442
+ // canvas (the spec's implicit release), touch and keyless ones too, and
443
+ // a capture cannot be taken while it is on. So every pointer that went
444
+ // down on the canvas and has not come up (`held`; Scene3DPlayer reports
445
+ // the ones its keyless handlers take through `pointer`) gets its capture
446
+ // back when a lock of ours ends, however it ends: when its
447
+ // pointerlockchange comes, not when pointerLockElement clears (Chromium
448
+ // clears it inside exitPointerLock and sends the event later). One that
449
+ // lifts beyond the canvas meanwhile is caught by the document (capture
450
+ // phase) and its own pointerup handed to its own handler, so a tap
451
+ // still jumps; one whose lift was never seen and cannot be captured
452
+ // again is let go of as a pointercancel would be. Both through `onLost`.
453
+ // - missing (no requestPointerLock: iOS, old browsers), throwing, its
454
+ // promise rejecting (a sandbox without allow-pointer-lock, Chrome's
455
+ // refusal of a re-lock just after Escape) or pointerlockerror: that drag
456
+ // goes on unlocked, on the pointer capture `down` took, so a drag that
457
+ // leaves the frame keeps turning and its release outside still ends it.
458
+ // The next drag asks again.
459
+ //
460
+ // Listeners, each only while it is needed: the window's blur and the
461
+ // document's visibilitychange while a mouse button or shift lock is held under the key;
462
+ // pointerlockchange while a drag has asked or shift lock wants it, and while our exit's event has
463
+ // not come (so the captures can be given back, a scene load between or
464
+ // not); the document's pointerup and pointercancel (capture phase) while a
465
+ // request of ours is on its way, the lock is ours, or our exit's event has
466
+ // not come; and, where requestPointerLock returns no promise (old Safari), while a request is on its way, with pointerlockerror
467
+ // too. A request that returns a promise is followed by the promise alone,
468
+ // so a scene load with one on its way leaves no listener behind, and a
469
+ // pointerlockerror (which does not say whose it is) is not taken for ours
470
+ // then. Without a promise an error may be another element's, so ours is
471
+ // still watched for SETTLE_MS after one.
472
+ const SETTLE_MS = 1000;
473
+
474
+ function makeMouseLock(canvas, gestures, lift, onShiftChange) {
475
+ const doc = canvas.ownerDocument ?? null;
476
+ const win = doc?.defaultView ?? null;
477
+ const supported = () => doc !== null && typeof canvas.requestPointerLock === 'function' && typeof doc.exitPointerLock === 'function';
478
+ // The mouse pointer down under the key: { id, x, y, asked, failed, had }.
479
+ // x, y is where the gestures last saw it (moved by movementX/Y while
480
+ // locked); `had` is whether it held the lock.
481
+ let drag = null;
482
+ // Intent while asking, and mode on only once the lock actually lands.
483
+ let shiftWanted = false;
484
+ let shiftOn = false;
485
+ // Our request on its way: { promise, timer }, or null.
486
+ let request = null;
487
+ // exitPointerLock called and its pointerlockchange not yet come. Not read
488
+ // off pointerLockElement: Chromium clears that inside the call and sends
489
+ // the event after. (If the event never came, `exitTimer` stands in.)
490
+ let exiting = false;
491
+ let exitTimer = null;
492
+ const on = { change: false, error: false, away: false, 'away-window': false, stray: false };
493
+ const locked = () => doc !== null && doc.pointerLockElement === canvas;
494
+ const wanted = () => shiftWanted || (drag !== null && drag.asked && !drag.failed);
495
+ const ours = () => locked() && !exiting;
496
+ // Every pointer down on the canvas, with the key or without: a lock that
497
+ // lands takes their captures (the Pointer Events spec's implicit release),
498
+ // and when a lock of ours ends each gets it back.
499
+ const down = new Set();
500
+ // Whether the lock now on (or just let go of) is ours.
501
+ let had = false;
502
+ // Whether the pointer is captured (or the capture could not be checked).
503
+ const capture = (id) => {
504
+ try {
505
+ canvas.setPointerCapture(id);
506
+ } catch {
507
+ // Not down any more (NotFoundError), or the lock still on.
508
+ return false;
509
+ }
510
+ return typeof canvas.hasPointerCapture !== 'function' || canvas.hasPointerCapture(id) !== false;
511
+ };
512
+ const release = () => {
513
+ if (!locked() || exiting) return;
514
+ exiting = true;
515
+ had = true;
516
+ try {
517
+ doc.exitPointerLock();
518
+ } catch {
519
+ exiting = false;
520
+ return;
521
+ }
522
+ clearTimeout(exitTimer);
523
+ exitTimer = setTimeout(() => {
524
+ exitTimer = null;
525
+ if (exiting && !locked()) onChange();
526
+ }, SETTLE_MS);
527
+ };
528
+ const toggle = (name, want, target, type, fn, options) => {
529
+ if (on[name] === want) return;
530
+ on[name] = want;
531
+ for (const t of type) (want ? target.addEventListener : target.removeEventListener).call(target, t, fn, options);
532
+ };
533
+ const sync = () => {
534
+ if (doc === null) return;
535
+ const eventOnly = request !== null && !request.promise;
536
+ // shiftWanted stays true for the whole time shiftOn is true too.
537
+ const away = drag !== null || shiftWanted;
538
+ toggle('change', eventOnly || exiting || shiftWanted || (drag !== null && drag.asked), doc, ['pointerlockchange'], onChange);
539
+ toggle('stray', request !== null || had || exiting, doc, ['pointerup', 'pointercancel'], onStray, true);
540
+ toggle('error', eventOnly, doc, ['pointerlockerror'], onError);
541
+ toggle('away', away, doc, ['visibilitychange'], onAway);
542
+ if (win !== null) toggle('away-window', away, win, ['blur'], onAway);
543
+ };
544
+ const endShift = () => {
545
+ if (!shiftWanted && !shiftOn) return;
546
+ shiftWanted = false;
547
+ shiftOn = false;
548
+ drag = null;
549
+ gestures.cancel();
550
+ onShiftChange();
551
+ };
552
+ // The drag ends with no tap: what it asked of the camera stays, the
553
+ // pointer is this file's no more.
554
+ const letGo = () => {
555
+ const id = drag.id;
556
+ drag = null;
557
+ gestures.up(id, performance.now(), true);
558
+ };
559
+ const done = (r) => {
560
+ if (request !== r) return false;
561
+ clearTimeout(r.timer);
562
+ request = null;
563
+ return true;
564
+ };
565
+ const failed = () => {
566
+ if (!locked() && shiftWanted) endShift();
567
+ if (drag !== null && drag.asked && !locked()) drag.failed = true;
568
+ sync();
569
+ };
570
+ // One owner: shift lock keeps it across mouse presses and releases.
571
+ const landed = () => {
572
+ if (locked()) {
573
+ had = true;
574
+ if (shiftWanted) {
575
+ shiftOn = true;
576
+ onShiftChange();
577
+ } else if (wanted()) drag.had = true;
578
+ else release();
579
+ }
580
+ sync();
581
+ };
582
+ const ask = () => {
583
+ if (!wanted() || shiftOn || drag?.had) return;
584
+ if (ours()) {
585
+ landed();
586
+ return;
587
+ }
588
+ // A request on its way, or our own exit not yet done: what settles it
589
+ // asks again if this drag still wants the lock.
590
+ if (request !== null || exiting) return;
591
+ let result;
592
+ try {
593
+ result = canvas.requestPointerLock();
594
+ } catch {
595
+ failed();
596
+ return;
597
+ }
598
+ const r = { promise: typeof result?.then === 'function', timer: null };
599
+ request = r;
600
+ if (r.promise) {
601
+ result.then(
602
+ () => {
603
+ if (done(r)) {
604
+ if (locked()) landed();
605
+ else failed();
606
+ }
607
+ },
608
+ () => {
609
+ if (done(r)) failed();
610
+ }
611
+ );
612
+ }
613
+ };
614
+ function onChange() {
615
+ if (locked()) {
616
+ if (request !== null && !request.promise) done(request);
617
+ landed();
618
+ return;
619
+ }
620
+ exiting = false;
621
+ clearTimeout(exitTimer);
622
+ exitTimer = null;
623
+ if (shiftOn) endShift();
624
+ if (had) {
625
+ had = false;
626
+ // One that cannot have it back came up while the lock had its
627
+ // capture, and its lift was not seen even by the document: it is let
628
+ // go of as a pointercancel would (the stick idles, no tap).
629
+ for (const id of [...down]) {
630
+ if (down.has(id) && !capture(id)) {
631
+ down.delete(id);
632
+ lift({ type: 'pointercancel', pointerId: id });
633
+ }
634
+ }
635
+ }
636
+ if (drag !== null && drag.had) letGo();
637
+ else ask();
638
+ sync();
639
+ }
640
+ function onError() {
641
+ const r = request;
642
+ if (r === null || r.promise) return;
643
+ // Maybe another element's: this drag goes on unlocked, and ours is
644
+ // still watched for a while in case it lands after all.
645
+ failed();
646
+ r.timer ??= setTimeout(() => {
647
+ if (!done(r)) return;
648
+ // A shift lock asked for meanwhile waited on this request, which never
649
+ // landed: it is off, so the next toggle asks again.
650
+ if (shiftWanted && !locked()) endShift();
651
+ sync();
652
+ }, SETTLE_MS);
653
+ }
654
+ // A held pointer lifted beyond the canvas while a lock of ours could have
655
+ // its capture: its own handler gets its own event, as the capture would
656
+ // have given it.
657
+ function onStray(event) {
658
+ if (event.target === canvas || !down.has(event.pointerId)) return;
659
+ lift(event);
660
+ }
661
+ function onAway(event) {
662
+ if (event.type === 'visibilitychange' && doc.visibilityState !== 'hidden') return;
663
+ endShift();
664
+ if (drag !== null) letGo();
665
+ release();
666
+ sync();
667
+ }
668
+ const want = () => {
669
+ if (drag.asked) return;
670
+ drag.asked = true;
671
+ ask();
672
+ sync();
673
+ };
674
+ return {
675
+ shiftLock: {
676
+ get active() {
677
+ return shiftOn;
678
+ },
679
+ toggle(available) {
680
+ if (shiftWanted || shiftOn) {
681
+ endShift();
682
+ release();
683
+ } else if (available && supported() && !exiting) {
684
+ // Never defer a shift-lock request until an unlock event: the
685
+ // request must run here, in the user's keydown or click gesture.
686
+ shiftWanted = true;
687
+ if (drag !== null) letGo();
688
+ ask();
689
+ }
690
+ sync();
691
+ },
692
+ },
693
+ capture,
694
+ held(id, isDown) {
695
+ if (isDown) down.add(id);
696
+ else down.delete(id);
697
+ },
698
+ down(event) {
699
+ if (event.pointerType !== 'mouse' || doc === null) return;
700
+ if (shiftWanted || shiftOn) return;
701
+ // One mouse: a press while another is held lost its pointerup.
702
+ if (drag !== null && drag.id !== event.pointerId) gestures.up(drag.id, performance.now(), true);
703
+ drag = { id: event.pointerId, x: event.clientX, y: event.clientY, asked: false, failed: false, had: false };
704
+ if (event.button === 2 && supported()) want();
705
+ else release();
706
+ sync();
707
+ },
708
+ // Undefined for a pointer that is not the drag: the caller hands it to
709
+ // the gestures as always.
710
+ move(event) {
711
+ if (shiftOn && event.pointerType === 'mouse') {
712
+ if (ours()) gestures.turn(event.movementX, event.movementY);
713
+ // A missing pointerup still lets go of a press, without ending
714
+ // shift lock or making that press a look-drag.
715
+ if (event.buttons === 0) gestures.up(event.pointerId, performance.now(), true);
716
+ return true;
717
+ }
718
+ if (drag === null || event.pointerId !== drag.id) return undefined;
719
+ if (event.buttons === 0) {
720
+ // Every button is up and no pointerup came.
721
+ letGo();
722
+ release();
723
+ sync();
724
+ return true;
725
+ }
726
+ if (ours()) {
727
+ drag.x += Number.isFinite(event.movementX) ? event.movementX : 0;
728
+ drag.y += Number.isFinite(event.movementY) ? event.movementY : 0;
729
+ } else {
730
+ drag.x = event.clientX;
731
+ drag.y = event.clientY;
732
+ }
733
+ const result = gestures.move(drag.id, drag.x, drag.y);
734
+ // A second button pressed while the drag is held (a chord comes as a
735
+ // pointermove): a tap no more, and the lock is asked for.
736
+ if (event.button >= 0 && (event.buttons & (event.buttons - 1)) !== 0) gestures.drag(drag.id);
737
+ if (gestures.roleOf(drag.id) === 'look' && supported()) want();
738
+ else if (!wanted()) release();
739
+ return result;
740
+ },
741
+ up(event) {
742
+ if (drag === null || event.pointerId !== drag.id) return;
743
+ drag = null;
744
+ release();
745
+ sync();
746
+ },
747
+ // Every pointer was let go of (a scene load, detach): so is the lock.
748
+ drop() {
749
+ endShift();
750
+ drag = null;
751
+ release();
752
+ sync();
753
+ },
754
+ };
755
+ }