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,583 @@
1
+ // Moment shots through the actual Player update and requested placement.
2
+ // The two frozen functions below are the orbit path before moment shots;
3
+ // the reference player cannot read orbitShot, even when it is set.
4
+ import assert from 'node:assert/strict';
5
+ import { readFileSync } from 'node:fs';
6
+ import * as THREE from 'three';
7
+
8
+ const beforeShot = `function driveOrbiting(scene, per, rt, props, dt) {
9
+ const keys = scene.keys;
10
+ per.camAngle += held(keys, ['ArrowRight'], ['ArrowLeft']) * props.turnSpeed * dt;
11
+ let ahead = held(keys, ['KeyW', 'ArrowUp'], ['KeyS', 'ArrowDown']);
12
+ let aside = held(keys, ['KeyD'], ['KeyA']);
13
+ const stick = scene.moveInput;
14
+ if (ahead === 0 && aside === 0 && stick?.active && Math.hypot(stick.x, stick.y) >= 0.15) {
15
+ ahead = -stick.y;
16
+ aside = stick.x;
17
+ }
18
+ const length = Math.hypot(ahead, aside);
19
+ if (length === 0) return null;
20
+ const scale = length > 1 ? 1 / length : 1;
21
+ const sin = Math.sin(per.camAngle);
22
+ const cos = Math.cos(per.camAngle);
23
+ const move = { x: (sin * ahead + cos * aside) * scale, z: (sin * aside - cos * ahead) * scale };
24
+ rt.facing += arc(Math.atan2(move.x, move.z) - rt.facing) * eased(FACE_RATE, dt);
25
+ return move;
26
+ }
27
+ function placeOrbiting(scene, id, dt) {
28
+ const actor = scene.getActor(id);
29
+ const props = actor?.components.Player;
30
+ const t = actor?.components.Transform;
31
+ const cam = scene.three?.camera;
32
+ if (!cam || !t || !props || props.$enabled === false) return;
33
+ const rt = actor.runtime;
34
+ const per = persistentOf(scene);
35
+ const chosen = orbitChoice(scene, props);
36
+ const look = scene.lookInput?.consume?.();
37
+ const before = per.camLastAt;
38
+ const jumped = Boolean(before) && Math.hypot(t.x - before.x, t.z - before.z) > TELEPORT_PER_FRAME;
39
+ per.camLastAt = { x: t.x, z: t.z };
40
+ const at = cam.position;
41
+ const state = (rt.orbit ??= { off: { x: 0, y: 0, z: 0 } });
42
+ // Placed on the frame before too: a frame this did not place on (the
43
+ // Player turned off, even by a collision callback after its update)
44
+ // breaks the chain.
45
+ const placed = typeof state.placedAt === 'number' && Math.abs(scene.time - dt - state.placedAt) < PLACED_WITHIN;
46
+ const mine = placed && !jumped && state.x === at.x && state.y === at.y && state.z === at.z;
47
+ if (mine) {
48
+ if (look && !look.locked) steerOrbit(per, chosen, look);
49
+ const k = eased(ORBIT_RATE, dt);
50
+ state.yaw += arc(per.camAngle - state.yaw) * k;
51
+ state.pitch += (chosen.pitch - state.pitch) * k;
52
+ state.range += (chosen.range - state.range) * k;
53
+ state.height = settle(state.height, state.heightTo, t.y, dt);
54
+ } else {
55
+ Object.assign(state, { yaw: per.camAngle, pitch: chosen.pitch, range: chosen.range, height: t.y, limit: Infinity, out: undefined, outRange: undefined, blendHeld: false, drawnOut: undefined });
56
+ }
57
+ state.heightTo = t.y;
58
+ const flat = Math.cos(state.pitch);
59
+ ray.dir.x = -flat * Math.sin(state.yaw);
60
+ ray.dir.y = Math.sin(state.pitch);
61
+ ray.dir.z = flat * Math.cos(state.yaw);
62
+ // From the point the camera is placed from, so what is tested is the
63
+ // camera that is drawn (less the takeover blend below, which is not).
64
+ ray.from.x = t.x;
65
+ ray.from.y = state.height + LOOK_HEIGHT;
66
+ ray.from.z = t.z;
67
+ const margin = lensMargin(scene, cam);
68
+ limitReach(scene.physics3d, state, margin, dt);
69
+ // Drawn at the nearer of its distance and the limit, out from the ball's
70
+ // start (the look point, or a point moved off a surface it is pressed to).
71
+ const reach = Math.max(Math.min(state.range, state.limit), 0);
72
+ const x = start.x + ray.dir.x * reach;
73
+ const y = start.y + ray.dir.y * reach;
74
+ const z = start.z + ray.dir.z * reach;
75
+ // How far from the look point it is placed, and the distance it was
76
+ // placed for, for the next frame's ease.
77
+ state.out = Math.hypot(x - ray.from.x, y - ray.from.y, z - ray.from.z);
78
+ state.outRange = state.range;
79
+ const off = takenOver(state.off, at, x, y, z, mine, jumped, dt);
80
+ state.blendHeld = Math.hypot(off.x, off.y, off.z) > BLEND_TESTED && blendHeldIn(scene.physics3d, state, off, x, y, z, margin, dt);
81
+ cam.position.set(x + off.x, y + off.y, z + off.z);
82
+ // How far from the look point it is drawn, for a held blend's ease.
83
+ state.drawnOut = Math.hypot(x + off.x - ray.from.x, y + off.y - ray.from.y, z + off.z - ray.from.z);
84
+ state.placedAt = scene.time;
85
+ state.x = at.x;
86
+ state.y = at.y;
87
+ state.z = at.z;
88
+ cam.lookAt(t.x, t.y + LOOK_HEIGHT, t.z);
89
+ // The actor the camera was placed for, for this frame's draw: its model is
90
+ // left out of the frame if the final camera is inside it
91
+ // (engine3d/ownmodel.js; the draw takes the name, a load drops it).
92
+ scene.orbitOwnModel = id;
93
+ }`;
94
+ const source = readFileSync(new URL('../behaviors/Player.jsx', import.meta.url), 'utf8').replace('export class Player', 'class Player');
95
+ const Player = new Function(`${source}\nreturn Player;`)();
96
+ const PlayerBefore = new Function(`${source}\n${beforeShot}\nreturn Player;`)();
97
+ const DT = 1 / 60;
98
+ const RATE = 10;
99
+ const LOOK_HEIGHT = 1.5 * (1.46 / 5);
100
+ const near = (a, b, message) => assert.ok(Math.abs(a - b) < 1e-10, `${message}: ${a} ~= ${b}`);
101
+ const vectorNear = (a, b, message) => { for (const k of ['x', 'y', 'z']) near(a[k], b[k], `${message}.${k}`); };
102
+ const point = (p) => ({ x: p.x, y: p.y, z: p.z });
103
+ const shotA = () => ({ look: { x: 3, y: 2, z: -2 }, distance: 5, pitch: 35, yaw: -60 });
104
+ const poseOf = (shot) => {
105
+ const p = Math.max(-89, Math.min(89, shot.pitch)) * (Math.PI / 180), y = shot.yaw * (Math.PI / 180);
106
+ return { x: shot.look.x - Math.cos(p) * Math.sin(y) * shot.distance,
107
+ y: shot.look.y + Math.sin(p) * shot.distance,
108
+ z: shot.look.z + Math.cos(p) * Math.cos(y) * shot.distance };
109
+ };
110
+
111
+ function harness({ keyed = true, rigid = true, PlayerClass = Player } = {}) {
112
+ const actor = { id: 'player', runtime: {}, components: {
113
+ Transform: { x: 0, y: 1, z: 0, rotationY: 0 }, Shape: { radius: .35, height: 1.4 },
114
+ Player: { ...PlayerClass.defaultProps },
115
+ } };
116
+ const camera = new THREE.PerspectiveCamera(83, 1.6, .1, 1000);
117
+ camera.position.set(8, 8, 8);
118
+ camera.lookAt(0, 1 + LOOK_HEIGHT, 0);
119
+ let lastLook;
120
+ const lookAt = camera.lookAt.bind(camera);
121
+ camera.lookAt = (x, y, z) => { lastLook = { x, y, z }; lookAt(x, y, z); };
122
+ let input = { yaw: 0, pitch: 0, zoom: 1, locked: false };
123
+ let consumed = 0;
124
+ let wall = null;
125
+ let casts = 0;
126
+ const calls = [];
127
+ const phys = {
128
+ ready: () => true, mass: () => 1,
129
+ castRay: () => ({ distance: 1 }), getVelocity: () => ({ x: 0, y: 0, z: 0 }),
130
+ setVelocity: (_, v) => calls.push(['velocity', { ...v }]),
131
+ resetForces: () => calls.push(['reset']),
132
+ applyImpulse: (_, v) => calls.push(['impulse', { ...v }]),
133
+ addForce: (_, v) => calls.push(['force', { ...v }]),
134
+ nearFixed: () => { casts += 1; return []; },
135
+ castRayFixedNormal: () => null,
136
+ castBallFixed: (_, __, max, radius) => {
137
+ casts += 1;
138
+ return wall !== null && wall - radius <= max ? { distance: Math.max(0, wall - radius), actorId: 'wall' } : null;
139
+ },
140
+ };
141
+ const scene = { cameraControl: keyed ? 'orbit' : null, cameraFollowsRigidly: rigid,
142
+ data: { engine: { camera: { fov: 83 } } }, physics3d: phys, three: { camera },
143
+ persistent: {}, time: 0, keys: new Set(), actorsWith: () => [], getActor: () => actor,
144
+ lookInput: { listen() {}, consume() { consumed += 1; const out = input; input = { yaw: 0, pitch: 0, zoom: 1, locked: false }; return out; } },
145
+ };
146
+ const frame = (dt = DT, keys = []) => {
147
+ calls.length = 0;
148
+ scene.keys = new Set(keys);
149
+ scene.time += dt;
150
+ new PlayerClass(actor.components.Player).update(actor, scene, dt);
151
+ scene.followCamera?.place(scene, actor.id, dt);
152
+ return { at: point(camera.position), q: camera.quaternion.toArray(), look: lastLook && { ...lastLook },
153
+ calls: structuredClone(calls), per: structuredClone(scene.persistent), choice: structuredClone(scene.cameraOrbit),
154
+ transform: { ...actor.components.Transform }, ownModel: scene.orbitOwnModel };
155
+ };
156
+ return { actor, camera, scene, frame, get look() { return lastLook; }, get consumed() { return consumed; },
157
+ get casts() { return casts; }, input(value) { input = value; }, wall(value) { wall = value; },
158
+ run(n) { for (let i = 0; i < n; i += 1) frame(); } };
159
+ }
160
+
161
+ function checkEase(h, shot, dt = DT) {
162
+ const at = point(h.camera.position), look = { ...h.look };
163
+ const target = poseOf(shot), k = 1 - Math.exp(-RATE * dt);
164
+ const dx = at.x - look.x, dy = at.y - look.y, dz = at.z - look.z;
165
+ const flat = Math.hypot(dx, dz), distance = Math.hypot(flat, dy);
166
+ const yaw = flat < distance * 1e-8 ? h.actor.runtime.orbitShot.yaw : Math.atan2(-dx, dz), pitch = Math.atan2(dy, flat);
167
+ const p = Math.max(-89, Math.min(89, shot.pitch)) * (Math.PI / 180), y = shot.yaw * (Math.PI / 180);
168
+ const targetYaw = Math.atan2(Math.cos(p) * Math.sin(y), Math.cos(p) * Math.cos(y));
169
+ const targetPitch = Math.atan2(Math.sin(p), Math.abs(Math.cos(p)));
170
+ const difference = Math.atan2(Math.sin(targetYaw - yaw), Math.cos(targetYaw - yaw));
171
+ const nextYaw = yaw + difference * k;
172
+ const nextPitch = Math.max(-89 * Math.PI / 180, Math.min(89 * Math.PI / 180, pitch + (targetPitch - pitch) * k));
173
+ const nextDistance = distance + (shot.distance - distance) * k;
174
+ const nextLook = {};
175
+ for (const key of ['x', 'y', 'z']) nextLook[key] = look[key] + (shot.look[key] - look[key]) * k;
176
+ const expected = {
177
+ x: nextLook.x - Math.cos(nextPitch) * Math.sin(nextYaw) * nextDistance,
178
+ y: nextLook.y + Math.sin(nextPitch) * nextDistance,
179
+ z: nextLook.z + Math.cos(nextPitch) * Math.cos(nextYaw) * nextDistance,
180
+ };
181
+ h.frame(dt);
182
+ const snapped = ['x', 'y', 'z'].every((key) => h.camera.position[key] === target[key] && h.look[key] === shot.look[key]);
183
+ for (const key of ['x', 'y', 'z']) {
184
+ if (snapped) {
185
+ assert.ok(Math.abs(h.camera.position[key] - expected[key]) < 1e-8, 'only a tiny final position snap');
186
+ assert.ok(Math.abs(h.look[key] - nextLook[key]) < 1e-8, 'only a tiny final look snap');
187
+ } else {
188
+ near(h.camera.position[key], expected[key], 'spherical position ease');
189
+ near(h.look[key], nextLook[key], 'look ease');
190
+ }
191
+ }
192
+ }
193
+
194
+ export async function runOrbitShotChecks() {
195
+ let checks = 0;
196
+ // An absent shot is the frozen pre-shot path, number for number through
197
+ // motion, turns, look, collision and an external camera takeover.
198
+ {
199
+ const now = harness(), before = harness({ PlayerClass: PlayerBefore });
200
+ for (let i = 0; i < 180; i += 1) {
201
+ for (const h of [now, before]) {
202
+ Object.assign(h.actor.components.Transform, { x: Math.sin(i / 30), y: 1 + Math.sin(i / 10) / 5, z: i / 50 });
203
+ h.wall(i > 40 && i < 90 ? 2 : null);
204
+ h.input({ yaw: .01, pitch: .001, zoom: 1.001, locked: false });
205
+ if (i === 120) h.camera.position.set(4, 5, 6);
206
+ }
207
+ assert.deepEqual(now.frame(i % 3 === 0 ? DT * 2 : DT, ['KeyW', 'ArrowRight']), before.frame(i % 3 === 0 ? DT * 2 : DT, ['KeyW', 'ArrowRight']));
208
+ }
209
+ assert.equal(now.actor.runtime.orbitShot, undefined);
210
+ checks += 1;
211
+ }
212
+ // Shots converge to the specified pose/look, hold without collision or
213
+ // lens changes, and moving the player never moves the held view.
214
+ {
215
+ const h = harness(); h.run(240);
216
+ const angle = h.scene.persistent.camAngle, choice = { ...h.scene.cameraOrbit };
217
+ h.scene.orbitShot = shotA();
218
+ const at = point(h.camera.position), look = { ...h.look };
219
+ h.frame(0);
220
+ vectorNear(h.camera.position, at, 'entry at zero dt');
221
+ vectorNear(h.look, look, 'entry look at zero dt');
222
+ const casts = h.casts;
223
+ h.wall(.5);
224
+ for (let i = 0; i < 300; i += 1) checkEase(h, h.scene.orbitShot);
225
+ assert.deepEqual(point(h.camera.position), poseOf(h.scene.orbitShot), 'exact settled shot');
226
+ assert.deepEqual(h.look, h.scene.orbitShot.look, 'exact settled look');
227
+ const heldPosition = h.camera.position.toArray(), heldOrientation = h.camera.quaternion.toArray();
228
+ h.actor.components.Transform.x = 12; h.run(60);
229
+ assert.deepEqual(h.camera.position.toArray(), heldPosition, 'bit-stable held position');
230
+ assert.deepEqual(h.camera.quaternion.toArray(), heldOrientation, 'bit-stable held orientation');
231
+ assert.equal(h.casts, casts, 'shots do not query collision');
232
+ assert.equal(h.camera.fov, 83);
233
+ assert.equal(h.scene.orbitOwnModel, h.actor.id);
234
+ assert.equal(h.scene.persistent.camAngle, angle);
235
+ assert.deepEqual(h.scene.cameraOrbit, choice);
236
+ checks += 1;
237
+ }
238
+ // Re-target mid-blend and mid-hold; equal objects are indistinguishable
239
+ // from keeping the original object, including when not yet settled.
240
+ {
241
+ const h = harness(), twin = harness(); h.run(240); twin.run(240);
242
+ h.scene.orbitShot = shotA(); twin.scene.orbitShot = shotA();
243
+ for (let i = 0; i < 240; i += 1) {
244
+ if (i === 5 || i === 180) {
245
+ h.scene.orbitShot = { look: { x: -2, y: 4 + i / 180, z: 3 }, distance: 8, pitch: -20, yaw: 145 };
246
+ twin.scene.orbitShot = structuredClone(h.scene.orbitShot);
247
+ }
248
+ const shot = h.scene.orbitShot;
249
+ h.scene.orbitShot = structuredClone(shot);
250
+ checkEase(h, shot, i % 2 === 0 ? DT : DT * 2);
251
+ twin.frame(i % 2 === 0 ? DT : DT * 2);
252
+ assert.deepEqual(h.camera.position.toArray(), twin.camera.position.toArray());
253
+ assert.deepEqual(h.look, twin.look);
254
+ }
255
+ checks += 1;
256
+ }
257
+ // Look and turn requests made while held are consumed, never applied;
258
+ // walking impulses are still the same as the reference player's.
259
+ {
260
+ const h = harness(), before = harness({ PlayerClass: PlayerBefore }); h.run(240); before.run(240);
261
+ const angle = h.scene.persistent.camAngle, choice = { ...h.scene.cameraOrbit };
262
+ h.scene.orbitShot = shotA();
263
+ for (let i = 0; i < 90; i += 1) {
264
+ h.input({ yaw: 1, pitch: .5, zoom: 2, locked: false });
265
+ assert.deepEqual(h.frame(DT, ['KeyW', 'KeyD', 'ArrowRight']).calls, before.frame(DT, ['KeyW', 'KeyD']).calls);
266
+ }
267
+ assert.equal(h.scene.persistent.camAngle, angle);
268
+ assert.deepEqual(h.scene.cameraOrbit, choice);
269
+ assert.equal(h.consumed, 330);
270
+ h.scene.orbitShot = undefined;
271
+ const at = point(h.camera.position), look = { ...h.look };
272
+ const own = before.frame().at, targetLook = { x: 0, y: 1 + LOOK_HEIGHT, z: 0 };
273
+ const k = 1 - Math.exp(-RATE * DT);
274
+ h.frame();
275
+ for (const key of ['x', 'y', 'z']) {
276
+ near(h.camera.position[key], at[key] + (own[key] - at[key]) * k, 'hand-back position');
277
+ near(h.look[key], look[key] + (targetLook[key] - look[key]) * k, 'hand-back look');
278
+ }
279
+ for (let i = 0; i < 300; i += 1) {
280
+ const lookBefore = { ...h.look };
281
+ const returning = h.actor.runtime.orbitShot.returning;
282
+ h.frame(); before.frame();
283
+ if (returning && h.actor.runtime.orbitShot.returning) {
284
+ for (const key of ['x', 'y', 'z']) near(h.look[key], lookBefore[key] + (targetLook[key] - lookBefore[key]) * k, 'continuous hand-back look');
285
+ } else {
286
+ assert.deepEqual(h.look, targetLook, 'completed return uses the exact player look');
287
+ }
288
+ const expected = h.camera.clone();
289
+ expected.lookAt(h.look.x, h.look.y, h.look.z);
290
+ for (const key of ['x', 'y', 'z', 'w']) near(h.camera.quaternion[key], expected.quaternion[key], 'orientation follows eased look');
291
+ }
292
+ vectorNear(h.camera.position, before.camera.position, 'hand-back resting pose');
293
+ vectorNear(h.look, before.look, 'hand-back resting look');
294
+ assert.equal(h.scene.persistent.camAngle, angle);
295
+ assert.deepEqual(h.scene.cameraOrbit, choice);
296
+ checks += 1;
297
+ }
298
+ // A look return finishes even at a constant 5 m/s. Align the drawn
299
+ // position on hand-back to isolate the look offset from the independent
300
+ // position takeover tail; after returning ends the entire drawn pose is
301
+ // bit-for-bit the never-shot player's on every matching walking frame.
302
+ {
303
+ const h = harness(), before = harness({ PlayerClass: PlayerBefore });
304
+ h.run(240); before.run(240);
305
+ h.scene.orbitShot = shotA();
306
+ let x = 0;
307
+ const walk = (a) => { a.actor.components.Transform.x = x; return a.frame(DT, ['KeyW']); };
308
+ for (let i = 0; i < 90; i += 1) {
309
+ x += 5 * DT;
310
+ walk(h); walk(before);
311
+ }
312
+ h.scene.orbitShot = null;
313
+ let endedAt = null;
314
+ for (let i = 0; i < 180; i += 1) {
315
+ x += 5 * DT;
316
+ const reference = walk(before);
317
+ if (i === 0) {
318
+ h.camera.position.copy(before.camera.position);
319
+ // Preserve shot ownership while aligning only the position tail.
320
+ Object.assign(h.actor.runtime.orbitShot, { atX: h.camera.position.x, atY: h.camera.position.y, atZ: h.camera.position.z });
321
+ }
322
+ const at = walk(h);
323
+ if (!h.actor.runtime.orbitShot.returning) {
324
+ endedAt ??= i;
325
+ assert.deepEqual(at.at, reference.at, 'walking position is bit-for-bit unchanged');
326
+ assert.deepEqual(at.look, reference.look, 'walking look is bit-for-bit unchanged');
327
+ assert.deepEqual(at.q, reference.q, 'walking orientation is bit-for-bit unchanged');
328
+ }
329
+ }
330
+ assert.ok(endedAt !== null && endedAt * DT <= 2, 'walking return ends within two seconds');
331
+ checks += 1;
332
+ }
333
+ // With an arbitrary shot position, walking still cannot keep the look
334
+ // return open. The existing position takeover settles independently,
335
+ // after which the full pose stays identical to the never-shot run.
336
+ {
337
+ const h = harness(), before = harness({ PlayerClass: PlayerBefore });
338
+ h.run(240); before.run(240);
339
+ h.scene.orbitShot = shotA(); h.run(90); before.run(90);
340
+ h.scene.orbitShot = null;
341
+ let endedAt = null;
342
+ for (let i = 0; i < 360; i += 1) {
343
+ for (const a of [h, before]) a.actor.components.Transform.x = (i + 1) * 5 * DT;
344
+ const at = h.frame(DT, ['KeyW']), reference = before.frame(DT, ['KeyW']);
345
+ if (!h.actor.runtime.orbitShot.returning) {
346
+ endedAt ??= i;
347
+ assert.deepEqual(at.look, reference.look);
348
+ }
349
+ if (i >= 300) {
350
+ assert.deepEqual(at.at, reference.at);
351
+ assert.deepEqual(at.q, reference.q);
352
+ }
353
+ }
354
+ assert.ok(endedAt !== null && endedAt * DT <= 2);
355
+ checks += 1;
356
+ }
357
+ // A teleport during the return clears its look offset, as the position
358
+ // takeover snaps, and uses the original lookAt call on that frame.
359
+ {
360
+ const h = harness(), before = harness({ PlayerClass: PlayerBefore });
361
+ h.run(240); before.run(240);
362
+ h.scene.orbitShot = shotA(); h.run(90); before.run(90);
363
+ h.scene.orbitShot = null; h.frame(); before.frame();
364
+ assert.equal(h.actor.runtime.orbitShot.returning, true);
365
+ h.actor.components.Transform.x = before.actor.components.Transform.x = 10;
366
+ const at = h.frame(), reference = before.frame();
367
+ assert.equal(h.actor.runtime.orbitShot.returning, false);
368
+ assert.deepEqual([h.actor.runtime.orbitShot.offX, h.actor.runtime.orbitShot.offY, h.actor.runtime.orbitShot.offZ], [0, 0, 0]);
369
+ assert.deepEqual(at.at, reference.at);
370
+ assert.deepEqual(at.look, reference.look);
371
+ assert.deepEqual(at.q, reference.q);
372
+ checks += 1;
373
+ }
374
+ // Entry from another system's orientation, even on the first frame,
375
+ // preserves that direction rather than aiming at the player at once.
376
+ {
377
+ const h = harness();
378
+ h.camera.lookAt(6, 2, -7);
379
+ const q = h.camera.quaternion.clone();
380
+ h.scene.orbitShot = shotA(); h.frame(0);
381
+ for (const key of ['x', 'y', 'z', 'w']) near(h.camera.quaternion[key], q[key], 'external camera entry');
382
+ checks += 1;
383
+ }
384
+ // Every invalid input is absent before any shot, and clears a held one
385
+ // exactly as null does. Ordinary clears work mid-blend as well.
386
+ const invalid = [undefined, null, {}, 1, 'shot', { ...shotA(), look: null },
387
+ { ...shotA(), look: { x: 1, y: 2 } }, { ...shotA(), distance: 0 }, { ...shotA(), distance: -1 },
388
+ ...['distance', 'pitch', 'yaw'].flatMap((key) => [NaN, Infinity, -Infinity, '1'].map((value) => ({ ...shotA(), [key]: value }))),
389
+ ...['x', 'y', 'z'].flatMap((key) => [NaN, Infinity, '1'].map((value) => ({ ...shotA(), look: { ...shotA().look, [key]: value } })))];
390
+ for (const value of invalid) {
391
+ const h = harness(), before = harness({ PlayerClass: PlayerBefore });
392
+ h.scene.orbitShot = value;
393
+ for (let i = 0; i < 12; i += 1) assert.deepEqual(h.frame(DT, ['ArrowLeft', 'KeyW']), before.frame(DT, ['ArrowLeft', 'KeyW']));
394
+ const cleared = harness(); cleared.run(240);
395
+ // Use fresh twins so both have exactly the same player's orbit choice.
396
+ const shot = harness(); shot.run(240);
397
+ for (const a of [shot, cleared]) { a.scene.orbitShot = shotA(); a.run(4); }
398
+ shot.scene.orbitShot = value; cleared.scene.orbitShot = null;
399
+ for (let i = 0; i < 30; i += 1) assert.deepEqual(shot.frame(), cleared.frame());
400
+ checks += 1;
401
+ }
402
+ // Disabled placement and a camera moved during the hand-back both reseed
403
+ // a continuing/new shot from the external system's actual direction.
404
+ for (const interruption of ['hold', 'return', 'gap']) {
405
+ const h = harness(); h.run(240); h.scene.orbitShot = shotA(); h.run(240);
406
+ if (interruption === 'return') {
407
+ h.scene.orbitShot = null; h.run(2);
408
+ } else {
409
+ h.actor.components.Player.$enabled = false; h.frame();
410
+ }
411
+ if (interruption === 'gap') {
412
+ const at = h.camera.position;
413
+ h.camera.lookAt(at.x + 8, at.y, at.z);
414
+ } else {
415
+ h.camera.position.set(4, 5, 6); h.camera.lookAt(12, 5, 6);
416
+ }
417
+ h.actor.components.Player.$enabled = true;
418
+ h.scene.orbitShot = shotA();
419
+ let previous = h.camera.quaternion.clone(), most = 0;
420
+ for (let i = 0; i < 300; i += 1) {
421
+ h.frame();
422
+ most = Math.max(most, previous.angleTo(h.camera.quaternion) * 180 / Math.PI);
423
+ previous.copy(h.camera.quaternion);
424
+ }
425
+ assert.ok(most < 30, `interrupted ${interruption}: ${most} degrees per frame`);
426
+ assert.deepEqual(point(h.camera.position), poseOf(h.scene.orbitShot));
427
+ assert.deepEqual(h.look, h.scene.orbitShot.look);
428
+ const settled = h.frame();
429
+ for (let i = 0; i < 60; i += 1) {
430
+ const at = h.frame(); assert.deepEqual(at.at, settled.at); assert.deepEqual(at.q, settled.q); assert.deepEqual(at.look, settled.look);
431
+ }
432
+ checks += 1;
433
+ }
434
+ // A moved camera while returning drops the look offset and behaves just
435
+ // like the pre-shot orbit camera taking over that drawn position.
436
+ {
437
+ const h = harness(); h.run(240); h.scene.orbitShot = shotA(); h.run(240);
438
+ h.scene.orbitShot = null; h.run(2);
439
+ h.camera.position.set(4, 5, 6); h.camera.lookAt(12, 5, 6);
440
+ const before = harness({ PlayerClass: PlayerBefore });
441
+ before.actor.runtime = { orbit: structuredClone(h.actor.runtime.orbit) };
442
+ before.scene.persistent = structuredClone(h.scene.persistent);
443
+ before.scene.cameraOrbit = structuredClone(h.scene.cameraOrbit);
444
+ before.scene.time = h.scene.time;
445
+ before.camera.copy(h.camera);
446
+ for (let i = 0; i < 60; i += 1) assert.deepEqual(h.frame(), before.frame());
447
+ assert.equal(h.actor.runtime.orbitShot.returning, false);
448
+ assert.deepEqual([h.actor.runtime.orbitShot.offX, h.actor.runtime.orbitShot.offY, h.actor.runtime.orbitShot.offZ], [0, 0, 0]);
449
+ checks += 1;
450
+ }
451
+ // A lookAt-only takeover must reseed a re-set shot even though the drawn
452
+ // position and frame chain still match the shot's last placement.
453
+ for (const duringReturn of [false, true]) {
454
+ const h = harness(); h.run(240);
455
+ const shot = { look: { x: 0, y: 1 + LOOK_HEIGHT, z: 0 }, distance: 5, pitch: 0, yaw: 0 };
456
+ h.scene.orbitShot = shot; h.run(300);
457
+ if (duringReturn) { h.scene.orbitShot = null; h.run(2); }
458
+ const position = h.camera.position.toArray();
459
+ h.camera.lookAt(h.camera.position.x, h.camera.position.y, h.camera.position.z + 10);
460
+ assert.deepEqual(h.camera.position.toArray(), position, 'only orientation changed');
461
+ h.scene.orbitShot = structuredClone(shot);
462
+ let previous = h.camera.quaternion.clone(), most = 0;
463
+ for (let i = 0; i < 300; i += 1) {
464
+ h.frame();
465
+ most = Math.max(most, previous.angleTo(h.camera.quaternion) * 180 / Math.PI);
466
+ previous.copy(h.camera.quaternion);
467
+ }
468
+ assert.ok(most < 30, `orientation-only ${duringReturn ? 'return' : 'hold'} interruption: ${most} degrees per frame`);
469
+ assert.deepEqual(point(h.camera.position), poseOf(shot));
470
+ assert.deepEqual(h.look, shot.look);
471
+ checks += 1;
472
+ }
473
+ // Straight-down/up shots previously lost azimuth when their horizontal
474
+ // displacement rounded away against a nonzero look point. Authored
475
+ // pitches beyond either limit now converge to the exact clamped pose.
476
+ for (const pitch of [90, -90, 270, -270]) {
477
+ const h = harness(); h.run(240);
478
+ const shot = { ...shotA(), pitch, yaw: 45 };
479
+ h.scene.orbitShot = shot;
480
+ let previous = h.camera.quaternion.clone(), most = 0;
481
+ for (let i = 0; i < 300; i += 1) {
482
+ h.frame();
483
+ most = Math.max(most, previous.angleTo(h.camera.quaternion) * 180 / Math.PI);
484
+ previous.copy(h.camera.quaternion);
485
+ const dx = h.camera.position.x - h.look.x, dy = h.camera.position.y - h.look.y, dz = h.camera.position.z - h.look.z;
486
+ assert.ok(Math.abs(Math.atan2(dy, Math.hypot(dx, dz))) <= 89 * (Math.PI / 180) + 1e-12, 'eased pitch stays off the poles');
487
+ }
488
+ assert.ok(most < 30, `pitch ${pitch}: ${most} degrees per frame`);
489
+ assert.deepEqual(point(h.camera.position), poseOf(shot));
490
+ assert.deepEqual(h.look, shot.look);
491
+ const settled = h.frame();
492
+ for (let i = 0; i < 60; i += 1) {
493
+ const at = h.frame(); assert.deepEqual(at.at, settled.at); assert.deepEqual(at.q, settled.q);
494
+ }
495
+ checks += 1;
496
+ }
497
+ // Entry from a truly vertical external camera uses its retained azimuth
498
+ // rather than atan2 of the rounded horizontal displacement.
499
+ {
500
+ const h = harness(); h.run(240);
501
+ const yaw = 45 * (Math.PI / 180);
502
+ h.camera.position.set(3, 9, 3);
503
+ h.camera.quaternion.setFromEuler(new THREE.Euler(-Math.PI / 2, -yaw, 0, 'YXZ'));
504
+ h.scene.orbitShot = { look: { x: 3, y: 1, z: 3 }, distance: 5, pitch: 90, yaw: 45 };
505
+ let previous = h.camera.quaternion.clone(), most = 0;
506
+ for (let i = 0; i < 300; i += 1) {
507
+ h.frame();
508
+ if (i === 0) near(h.actor.runtime.orbitShot.yaw, yaw, 'vertical entry retains azimuth');
509
+ most = Math.max(most, previous.angleTo(h.camera.quaternion) * 180 / Math.PI);
510
+ previous.copy(h.camera.quaternion);
511
+ }
512
+ assert.ok(most < 30, `vertical entry: ${most} degrees per frame`);
513
+ assert.deepEqual(point(h.camera.position), poseOf(h.scene.orbitShot));
514
+ checks += 1;
515
+ }
516
+ // Mutating a level shot to face the opposing direction swings around
517
+ // the look point rather than passing through it and reversing lookAt.
518
+ {
519
+ const h = harness(); h.run(240);
520
+ const shot = { look: { x: 0, y: 1 + LOOK_HEIGHT, z: 0 }, distance: 5, pitch: 0, yaw: 0 };
521
+ h.scene.orbitShot = shot; h.run(300);
522
+ shot.yaw = 180;
523
+ let previous = h.camera.quaternion.clone(), most = 0;
524
+ for (let i = 0; i < 300; i += 1) {
525
+ h.frame();
526
+ most = Math.max(most, previous.angleTo(h.camera.quaternion) * 180 / Math.PI);
527
+ previous.copy(h.camera.quaternion);
528
+ near(Math.hypot(h.camera.position.x - h.look.x, h.camera.position.y - h.look.y, h.camera.position.z - h.look.z), 5, 'opposing shot keeps its range');
529
+ }
530
+ assert.ok(most < 30, `opposing shots: ${most} degrees per frame`);
531
+ assert.deepEqual(point(h.camera.position), poseOf(shot));
532
+ assert.deepEqual(h.look, shot.look);
533
+ const settled = h.frame();
534
+ for (let i = 0; i < 120; i += 1) {
535
+ const at = h.frame(); assert.deepEqual(at.at, settled.at); assert.deepEqual(at.q, settled.q); assert.deepEqual(at.look, settled.look);
536
+ }
537
+ checks += 1;
538
+ }
539
+ // Shot state belongs to its actor, survives a runtime transfer, and starts
540
+ // from the currently drawn pose when interrupted during the hand-back.
541
+ {
542
+ const h = harness(); h.run(240); h.scene.orbitShot = shotA(); h.run(180);
543
+ const transferred = { ...h.actor, runtime: structuredClone(h.actor.runtime) };
544
+ h.actor.runtime = transferred.runtime;
545
+ h.scene.orbitShot = null; h.run(2);
546
+ h.scene.orbitShot = { ...shotA(), yaw: 120 };
547
+ checkEase(h, h.scene.orbitShot);
548
+ assert.equal(h.actor.runtime.orbitShot.active, true);
549
+ checks += 1;
550
+ }
551
+ // Clearing still uses the original collided takeover blend.
552
+ {
553
+ const h = harness(); h.run(240); h.scene.orbitShot = shotA(); h.run(240);
554
+ h.wall(1.5); const casts = h.casts;
555
+ h.scene.orbitShot = null; h.frame();
556
+ assert.ok(h.casts > casts, 'hand-back sweeps its drawn point');
557
+ const t = h.actor.components.Transform;
558
+ assert.ok(h.camera.position.distanceTo(new THREE.Vector3(t.x, t.y + LOOK_HEIGHT, t.z)) <= 1.25 + 1e-10);
559
+ checks += 1;
560
+ }
561
+ // Under a held shot the camera cannot swing, so left/right strafe exactly
562
+ // as A/D do, and the player's own camera angle stays where it was.
563
+ for (const [arrow, letter] of [['ArrowRight', 'KeyD'], ['ArrowLeft', 'KeyA']]) {
564
+ const a = harness(), b = harness();
565
+ for (const h of [a, b]) { h.run(60); h.scene.orbitShot = shotA(); h.run(4); }
566
+ const angle = a.scene.persistent.camAngle;
567
+ for (let i = 0; i < 30; i += 1) assert.deepEqual(a.frame(DT, [arrow, 'KeyW']), b.frame(DT, [letter, 'KeyW']));
568
+ assert.equal(a.scene.persistent.camAngle, angle);
569
+ assert.ok(a.frame(DT, [arrow]).calls.length > 0, `${arrow} moves under a shot`);
570
+ checks += 1;
571
+ }
572
+ // Both keyless follow modes ignore even a throwing orbitShot getter.
573
+ for (const rigid of [false, true]) {
574
+ const h = harness({ keyed: false, rigid }), before = harness({ keyed: false, rigid, PlayerClass: PlayerBefore });
575
+ Object.defineProperty(h.scene, 'orbitShot', { get() { throw new Error('keyless read orbitShot'); } });
576
+ for (let i = 0; i < 30; i += 1) assert.deepEqual(h.frame(DT, ['KeyW', 'ArrowRight']), before.frame(DT, ['KeyW', 'ArrowRight']));
577
+ assert.equal(h.actor.runtime.orbitShot, undefined);
578
+ checks += 1;
579
+ }
580
+ return checks;
581
+ }
582
+
583
+ if (import.meta.url === `file://${process.argv[1]}`) console.log(`orbit shot: ${await runOrbitShotChecks()} checks`);