castle-web-cli 0.4.232 → 0.4.234

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (587) hide show
  1. package/dist/agent-failures.d.ts +8 -0
  2. package/dist/agent-failures.js +19 -2
  3. package/dist/agent-prompts.d.ts +1 -1
  4. package/dist/agent-prompts.js +10 -3
  5. package/dist/agent.d.ts +64 -3
  6. package/dist/agent.js +170 -81
  7. package/dist/api.d.ts +11 -0
  8. package/dist/api.js +43 -0
  9. package/dist/bundle.d.ts +64 -0
  10. package/dist/bundle.js +558 -2
  11. package/dist/castle-host/host.d.ts +18 -2
  12. package/dist/castle-host/host.js +844 -39
  13. package/dist/castleJson.d.ts +23 -2
  14. package/dist/castleJson.js +46 -2
  15. package/dist/check.d.ts +3 -1
  16. package/dist/check.js +20 -3
  17. package/dist/chunkLoader.d.ts +3 -0
  18. package/dist/chunkLoader.js +111 -0
  19. package/dist/devParty.d.ts +26 -0
  20. package/dist/devParty.js +231 -0
  21. package/dist/devSaveStorage.js +4 -0
  22. package/dist/devSessionStorage.js +50 -2
  23. package/dist/devSocial.d.ts +24 -0
  24. package/dist/devSocial.js +70 -0
  25. package/dist/ide.d.ts +2 -0
  26. package/dist/ide.js +119 -15
  27. package/dist/importPinMismatch.d.ts +22 -0
  28. package/dist/importPinMismatch.js +77 -0
  29. package/dist/importRegression.js +3 -15
  30. package/dist/imports.d.ts +10 -3
  31. package/dist/imports.js +88 -20
  32. package/dist/index.js +11 -4
  33. package/dist/init.js +1 -1
  34. package/dist/platformDoc.js +22 -0
  35. package/dist/routerFences.d.ts +5 -0
  36. package/dist/routerFences.js +12 -2
  37. package/dist/save-deck.d.ts +25 -1
  38. package/dist/save-deck.js +178 -9
  39. package/dist/serve.js +32 -11
  40. package/dist/shell/assets/{index-D2tWM896.js → index-DulbYIJm.js} +97 -97
  41. package/dist/shell/assets/index-MVLfNYd9.css +1 -0
  42. package/dist/shell/index.html +2 -2
  43. package/dist/taskSteer.d.ts +13 -0
  44. package/dist/taskSteer.js +22 -2
  45. package/dist/vitePlugins.d.ts +2 -1
  46. package/dist/vitePlugins.js +13 -0
  47. package/kits/base/castle.json +1 -1
  48. package/kits/base/package-lock.json +1 -1
  49. package/kits/base/sdk/README.md +339 -5
  50. package/kits/base/sdk/avatar.d.ts +6 -2
  51. package/kits/base/sdk/avatar.js +12 -4
  52. package/kits/base/sdk/castle.d.ts +7 -3
  53. package/kits/base/sdk/castle.js +2 -0
  54. package/kits/base/sdk/commands.d.ts +176 -1
  55. package/kits/base/sdk/commands.js +3 -0
  56. package/kits/base/sdk/display.d.ts +3 -0
  57. package/kits/base/sdk/display.js +9 -3
  58. package/kits/base/sdk/hub.d.ts +37 -6
  59. package/kits/base/sdk/hub.js +63 -4
  60. package/kits/base/sdk/multiplayer.d.ts +7 -1
  61. package/kits/base/sdk/multiplayer.js +148 -32
  62. package/kits/base/sdk/multiplayerProtocol.d.ts +2 -0
  63. package/kits/base/sdk/party.d.ts +23 -0
  64. package/kits/base/sdk/party.js +91 -0
  65. package/kits/base/sdk/reconnectBudget.d.ts +23 -0
  66. package/kits/base/sdk/reconnectBudget.js +96 -0
  67. package/kits/base/sdk/save.d.ts +38 -1
  68. package/kits/base/sdk/save.js +81 -7
  69. package/kits/base/sdk/server/hub.d.ts +117 -0
  70. package/kits/base/sdk/server/hub.js +119 -2
  71. package/kits/base/sdk/server/platformHandle.d.ts +43 -1
  72. package/kits/base/sdk/server/storage.d.ts +17 -0
  73. package/kits/base/sdk/server/storage.js +65 -3
  74. package/kits/base/sdk/server/wrapper.d.ts +43 -6
  75. package/kits/base/sdk/server/wrapper.js +93 -9
  76. package/kits/base/sdk/social.d.ts +9 -0
  77. package/kits/base/sdk/social.js +5 -0
  78. package/kits/hub-game/CLAUDE.md +451 -13
  79. package/kits/hub-game/README.md +63 -0
  80. package/kits/hub-game/blueprints/avatar-10.scene +28 -0
  81. package/kits/hub-game/blueprints/avatar-11.scene +28 -0
  82. package/kits/hub-game/blueprints/avatar-12.scene +28 -0
  83. package/kits/hub-game/blueprints/avatar-13.scene +28 -0
  84. package/kits/hub-game/blueprints/avatar-14.scene +28 -0
  85. package/kits/hub-game/blueprints/avatar-15.scene +28 -0
  86. package/kits/hub-game/blueprints/avatar-4.scene +28 -0
  87. package/kits/hub-game/blueprints/avatar-5.scene +28 -0
  88. package/kits/hub-game/blueprints/avatar-6.scene +28 -0
  89. package/kits/hub-game/blueprints/avatar-7.scene +28 -0
  90. package/kits/hub-game/blueprints/avatar-8.scene +28 -0
  91. package/kits/hub-game/blueprints/avatar-9.scene +28 -0
  92. package/kits/hub-game/castle.json +5 -5
  93. package/kits/hub-game/code/client/act.js +312 -0
  94. package/kits/hub-game/code/client/actionLayout.js +147 -0
  95. package/kits/hub-game/code/client/actionOverflow.js +556 -0
  96. package/kits/hub-game/code/client/actorBudget.js +47 -0
  97. package/kits/hub-game/code/client/arrivalCamera.js +50 -0
  98. package/kits/hub-game/code/client/askSlot.js +117 -0
  99. package/kits/hub-game/code/client/attention.js +11 -2
  100. package/kits/hub-game/code/client/avatar.js +311 -35
  101. package/kits/hub-game/code/client/avatarCap.js +228 -0
  102. package/kits/hub-game/code/client/avatarColors.js +70 -0
  103. package/kits/hub-game/code/client/avatarFaces.js +21 -0
  104. package/kits/hub-game/code/client/avatarShare.js +253 -0
  105. package/kits/hub-game/code/client/backVisibility.js +13 -0
  106. package/kits/hub-game/code/client/ballot.js +472 -0
  107. package/kits/hub-game/code/client/build.js +38 -0
  108. package/kits/hub-game/code/client/chat.js +41 -5
  109. package/kits/hub-game/code/client/chatModeration.js +5 -0
  110. package/kits/hub-game/code/client/chrome.js +2144 -160
  111. package/kits/hub-game/code/client/companion.js +716 -0
  112. package/kits/hub-game/code/client/companionDress.js +99 -0
  113. package/kits/hub-game/code/client/crowdNames.js +241 -0
  114. package/kits/hub-game/code/client/decor.js +515 -0
  115. package/kits/hub-game/code/client/defaultEnvironment.js +194 -0
  116. package/kits/hub-game/code/client/doorErrors.js +39 -0
  117. package/kits/hub-game/code/client/earned.js +131 -0
  118. package/kits/hub-game/code/client/emoteBubble.js +75 -0
  119. package/kits/hub-game/code/client/fall.js +18 -0
  120. package/kits/hub-game/code/client/farAvatars.js +233 -0
  121. package/kits/hub-game/code/client/firstJoin.js +9 -2
  122. package/kits/hub-game/code/client/fpsTelemetry.js +50 -0
  123. package/kits/hub-game/code/client/frameBatch.js +5 -0
  124. package/kits/hub-game/code/client/grab.js +368 -29
  125. package/kits/hub-game/code/client/hookLayer.js +385 -20
  126. package/kits/hub-game/code/client/hudCopy.js +51 -0
  127. package/kits/hub-game/code/client/hudRate.js +20 -0
  128. package/kits/hub-game/code/client/idle.js +177 -24
  129. package/kits/hub-game/code/client/interestCap.js +81 -0
  130. package/kits/hub-game/code/client/invites.js +231 -0
  131. package/kits/hub-game/code/client/joinError.js +9 -0
  132. package/kits/hub-game/code/client/keys.js +36 -0
  133. package/kits/hub-game/code/client/labelsNear.js +234 -0
  134. package/kits/hub-game/code/client/landscapeLayout.js +17 -0
  135. package/kits/hub-game/code/client/layoutCache.js +264 -0
  136. package/kits/hub-game/code/client/loadTelemetry.js +20 -0
  137. package/kits/hub-game/code/client/loadingCover.js +148 -0
  138. package/kits/hub-game/code/client/loadingEntry.js +8 -0
  139. package/kits/hub-game/code/client/menuIcons.js +34 -0
  140. package/kits/hub-game/code/client/menuRows.js +43 -0
  141. package/kits/hub-game/code/client/modelReady.js +7 -0
  142. package/kits/hub-game/code/client/pack.js +6 -2
  143. package/kits/hub-game/code/client/packFormat.js +3 -3
  144. package/kits/hub-game/code/client/padCueArrival.js +23 -0
  145. package/kits/hub-game/code/client/padCues.js +112 -0
  146. package/kits/hub-game/code/client/padOccupancy.js +88 -0
  147. package/kits/hub-game/code/client/padReadability.js +26 -0
  148. package/kits/hub-game/code/client/padRings.js +69 -0
  149. package/kits/hub-game/code/client/pushVisit.js +14 -0
  150. package/kits/hub-game/code/client/quality.js +205 -0
  151. package/kits/hub-game/code/client/qualityEntry.js +55 -0
  152. package/kits/hub-game/code/client/rehello.js +167 -0
  153. package/kits/hub-game/code/client/safeLayout.js +338 -0
  154. package/kits/hub-game/code/client/safeStyle.js +42 -0
  155. package/kits/hub-game/code/client/say.js +12 -3
  156. package/kits/hub-game/code/client/shot.js +146 -0
  157. package/kits/hub-game/code/client/shotFit.js +56 -0
  158. package/kits/hub-game/code/client/signIn.js +28 -0
  159. package/kits/hub-game/code/client/sound.js +63 -8
  160. package/kits/hub-game/code/client/soundscape.js +1151 -0
  161. package/kits/hub-game/code/client/soundscapeActions.js +99 -0
  162. package/kits/hub-game/code/client/soundscapeAmbience.js +453 -0
  163. package/kits/hub-game/code/client/soundscapeBaked.js +143 -0
  164. package/kits/hub-game/code/client/soundscapeBusker.js +217 -0
  165. package/kits/hub-game/code/client/soundscapeCourt.js +200 -0
  166. package/kits/hub-game/code/client/soundscapeCrowd.js +331 -0
  167. package/kits/hub-game/code/client/soundscapeCues.js +362 -0
  168. package/kits/hub-game/code/client/soundscapeMap.js +181 -0
  169. package/kits/hub-game/code/client/soundscapeMarket.js +176 -0
  170. package/kits/hub-game/code/client/soundscapeMusic.js +126 -0
  171. package/kits/hub-game/code/client/soundscapeMusicEngine.js +460 -0
  172. package/kits/hub-game/code/client/soundscapeSimlish.js +737 -0
  173. package/kits/hub-game/code/client/soundscapeSongs.js +127 -0
  174. package/kits/hub-game/code/client/soundscapeSongsRound3.js +63 -0
  175. package/kits/hub-game/code/client/soundscapeSynthesis.js +168 -0
  176. package/kits/hub-game/code/client/soundscapeUi.js +211 -0
  177. package/kits/hub-game/code/client/soundscapeVoice.js +1209 -0
  178. package/kits/hub-game/code/client/soundscapeWaves.js +206 -0
  179. package/kits/hub-game/code/client/spin.js +101 -0
  180. package/kits/hub-game/code/client/state.js +162 -1
  181. package/kits/hub-game/code/client/stuck.js +259 -0
  182. package/kits/hub-game/code/client/talk.js +714 -59
  183. package/kits/hub-game/code/client/tiers.js +543 -52
  184. package/kits/hub-game/code/client/toastBand.js +37 -0
  185. package/kits/hub-game/code/client/together.js +39 -2
  186. package/kits/hub-game/code/client/visibility.js +43 -0
  187. package/kits/hub-game/code/client/weakestLookBake.js +92 -0
  188. package/kits/hub-game/code/client/weakestTier.js +295 -0
  189. package/kits/hub-game/code/client/wear.js +461 -170
  190. package/kits/hub-game/code/client/worldLabels.js +241 -0
  191. package/kits/hub-game/code/client/yours.js +200 -0
  192. package/kits/hub-game/code/companionSpec.js +45 -0
  193. package/kits/hub-game/code/npcDisplayText.js +55 -0
  194. package/kits/hub-game/code/privateText.js +7 -0
  195. package/kits/hub-game/code/server/act.js +124 -0
  196. package/kits/hub-game/code/server/actions.js +138 -0
  197. package/kits/hub-game/code/server/actors.js +11 -2
  198. package/kits/hub-game/code/server/analytics.js +83 -0
  199. package/kits/hub-game/code/server/anonymousEntry.js +49 -0
  200. package/kits/hub-game/code/server/arrivalPose.js +36 -0
  201. package/kits/hub-game/code/server/ask.js +155 -0
  202. package/kits/hub-game/code/server/ballot.js +539 -0
  203. package/kits/hub-game/code/server/cells.js +100 -0
  204. package/kits/hub-game/code/server/companion.js +107 -0
  205. package/kits/hub-game/code/server/cues.js +70 -0
  206. package/kits/hub-game/code/server/decor.js +269 -0
  207. package/kits/hub-game/code/server/doorAnalytics.js +52 -0
  208. package/kits/hub-game/code/server/earned.js +478 -0
  209. package/kits/hub-game/code/server/frameBatch.js +183 -0
  210. package/kits/hub-game/code/server/friendBests.js +166 -0
  211. package/kits/hub-game/code/server/friendsAmong.js +272 -0
  212. package/kits/hub-game/code/server/history.js +7 -0
  213. package/kits/hub-game/code/server/hub.js +2510 -95
  214. package/kits/hub-game/code/server/idle.js +60 -12
  215. package/kits/hub-game/code/server/index.js +28 -6
  216. package/kits/hub-game/code/server/invites.js +19 -0
  217. package/kits/hub-game/code/server/labels.js +36 -2
  218. package/kits/hub-game/code/server/loadAbandon.js +106 -0
  219. package/kits/hub-game/code/server/manifest.js +586 -7
  220. package/kits/hub-game/code/server/menu.js +161 -0
  221. package/kits/hub-game/code/server/npcs.js +1025 -113
  222. package/kits/hub-game/code/server/observe.js +408 -0
  223. package/kits/hub-game/code/server/padOccupancy.js +85 -0
  224. package/kits/hub-game/code/server/party.js +2 -2
  225. package/kits/hub-game/code/server/players.js +30 -0
  226. package/kits/hub-game/code/server/resumePose.js +152 -0
  227. package/kits/hub-game/code/server/say.js +1 -1
  228. package/kits/hub-game/code/server/shot.js +110 -0
  229. package/kits/hub-game/code/server/standing.js +123 -0
  230. package/kits/hub-game/code/server/storageLimit.js +187 -0
  231. package/kits/hub-game/code/server/vis.js +175 -0
  232. package/kits/hub-game/code/server/wear.js +12 -0
  233. package/kits/hub-game/code/server/yours.js +59 -0
  234. package/kits/hub-game/code/shared/act.js +35 -0
  235. package/kits/hub-game/code/shared/cues.js +9 -0
  236. package/kits/hub-game/code/shared/danceIdle.js +28 -0
  237. package/kits/hub-game/code/shared/decor.js +41 -0
  238. package/kits/hub-game/code/shared/loadStages.js +12 -0
  239. package/kits/hub-game/code/shared/quality.js +74 -0
  240. package/kits/hub-game/code/shared/say.js +2 -0
  241. package/kits/hub-game/code/shared/shot.js +53 -0
  242. package/kits/hub-game/code/shared/spin.js +57 -0
  243. package/kits/hub-game/code/systems/hub.js +1753 -202
  244. package/kits/hub-game/docs/analytics.md +279 -0
  245. package/kits/hub-game/docs/content-pack.md +1 -1
  246. package/kits/hub-game/docs/contract.md +3475 -77
  247. package/kits/hub-game/docs/home-pieces.md +71 -0
  248. package/kits/hub-game/docs/observed-progress.md +252 -0
  249. package/kits/hub-game/main.jsx +2 -0
  250. package/kits/hub-game/models/avatar-10.pxmodel +28 -0
  251. package/kits/hub-game/models/avatar-11.pxmodel +28 -0
  252. package/kits/hub-game/models/avatar-12.pxmodel +27 -0
  253. package/kits/hub-game/models/avatar-13.pxmodel +24 -0
  254. package/kits/hub-game/models/avatar-14.pxmodel +29 -0
  255. package/kits/hub-game/models/avatar-15.pxmodel +24 -0
  256. package/kits/hub-game/models/avatar-4.pxmodel +29 -0
  257. package/kits/hub-game/models/avatar-5.pxmodel +27 -0
  258. package/kits/hub-game/models/avatar-6.pxmodel +26 -0
  259. package/kits/hub-game/models/avatar-7.pxmodel +25 -0
  260. package/kits/hub-game/models/avatar-8.pxmodel +24 -0
  261. package/kits/hub-game/models/avatar-9.pxmodel +30 -0
  262. package/kits/hub-game/models/earned/badge-round.pxmodel +100 -0
  263. package/kits/hub-game/models/earned/badge-shield.pxmodel +117 -0
  264. package/kits/hub-game/models/earned/badge-star.pxmodel +87 -0
  265. package/kits/hub-game/models/earned/belt-plain.pxmodel +72 -0
  266. package/kits/hub-game/models/earned/held-ball.pxmodel +43 -0
  267. package/kits/hub-game/models/earned/held-lantern.pxmodel +85 -0
  268. package/kits/hub-game/models/earned/held-net.pxmodel +57 -0
  269. package/kits/hub-game/models/earned/held-trophy.pxmodel +109 -0
  270. package/kits/hub-game/models/earned/pin-round.pxmodel +62 -0
  271. package/kits/hub-game/models/earned/sash-plain.pxmodel +66 -0
  272. package/kits/hub-game/models/earned/square/belt-plain.pxmodel +104 -0
  273. package/kits/hub-game/models/earned/square/sash-plain.pxmodel +98 -0
  274. package/kits/hub-game/models/hats/bat-clip.pxmodel +206 -0
  275. package/kits/hub-game/models/hats/beekeeper.pxmodel +149 -0
  276. package/kits/hub-game/models/hats/cap.pxmodel +162 -0
  277. package/kits/hub-game/models/hats/captain.pxmodel +178 -0
  278. package/kits/hub-game/models/hats/crooked-top.pxmodel +172 -0
  279. package/kits/hub-game/models/hats/flower-crown.pxmodel +451 -0
  280. package/kits/hub-game/models/hats/foam-crown.pxmodel +179 -0
  281. package/kits/hub-game/models/hats/lantern.pxmodel +230 -0
  282. package/kits/hub-game/models/hats/laurel.pxmodel +533 -0
  283. package/kits/hub-game/models/hats/lighthouse.pxmodel +96 -0
  284. package/kits/hub-game/models/hats/sailor.pxmodel +141 -0
  285. package/kits/hub-game/models/hats/souwester.pxmodel +131 -0
  286. package/kits/hub-game/models/hats/straw.pxmodel +139 -0
  287. package/kits/hub-game/models/hats/sunflower.pxmodel +406 -0
  288. package/kits/hub-game/models/hats/sweatband.pxmodel +112 -0
  289. package/kits/hub-game/models/hats/witch.pxmodel +147 -0
  290. package/kits/hub-game/package-lock.json +10 -1
  291. package/kits/hub-game/package.json +6 -2
  292. package/kits/hub-game/play/player.js +142 -0
  293. package/kits/hub-game/play/registry.js +47 -0
  294. package/kits/hub-game/play.jsx +37 -0
  295. package/kits/hub-game/scripts/check.mjs +117 -16
  296. package/kits/hub-game/scripts/companion-follower-wire.json +1 -0
  297. package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +132 -0
  298. package/kits/hub-game/scripts/fixtures/decor-keyless.json +293 -0
  299. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +26 -0
  300. package/kits/hub-game/scripts/fixtures/fake-dom.mjs +123 -0
  301. package/kits/hub-game/scripts/fixtures/interest-legacy.json +385 -0
  302. package/kits/hub-game/scripts/fixtures/npc-notes-v1.77.jsonl +4 -0
  303. package/kits/hub-game/scripts/fixtures/vis-shared-wire.json +1 -0
  304. package/kits/hub-game/scripts/gen-avatars.mjs +933 -16
  305. package/kits/hub-game/scripts/gen-earned.mjs +285 -0
  306. package/kits/hub-game/scripts/gen-hats.mjs +827 -0
  307. package/kits/hub-game/scripts/grab.before-orbit.mjs +400 -0
  308. package/kits/hub-game/scripts/pose-storage-fixture.mjs +46 -0
  309. package/kits/hub-game/scripts/soundscape-wave-analysis.mjs +125 -0
  310. package/kits/hub-game/scripts/test-act-client.mjs +186 -0
  311. package/kits/hub-game/scripts/test-act.mjs +171 -0
  312. package/kits/hub-game/scripts/test-action-layout.mjs +80 -0
  313. package/kits/hub-game/scripts/test-action-observers.mjs +46 -0
  314. package/kits/hub-game/scripts/test-actions-client.mjs +853 -0
  315. package/kits/hub-game/scripts/test-actions.mjs +298 -0
  316. package/kits/hub-game/scripts/test-actor-budget.mjs +44 -0
  317. package/kits/hub-game/scripts/test-actors.mjs +38 -23
  318. package/kits/hub-game/scripts/test-analytics.mjs +76 -0
  319. package/kits/hub-game/scripts/test-anonymous-entry.mjs +28 -0
  320. package/kits/hub-game/scripts/test-arrival-pose-server.mjs +196 -0
  321. package/kits/hub-game/scripts/test-arrival-pose.mjs +24 -0
  322. package/kits/hub-game/scripts/test-ask-client.mjs +358 -0
  323. package/kits/hub-game/scripts/test-ask-slot.mjs +85 -0
  324. package/kits/hub-game/scripts/test-ask.mjs +269 -0
  325. package/kits/hub-game/scripts/test-attention.mjs +10 -1
  326. package/kits/hub-game/scripts/test-avatar-cap.mjs +379 -0
  327. package/kits/hub-game/scripts/test-avatar-colors.mjs +72 -0
  328. package/kits/hub-game/scripts/test-avatar-models.mjs +181 -0
  329. package/kits/hub-game/scripts/test-avatar-share.mjs +318 -0
  330. package/kits/hub-game/scripts/test-avatar-wire.mjs +792 -0
  331. package/kits/hub-game/scripts/test-avatar.mjs +584 -7
  332. package/kits/hub-game/scripts/test-back-visibility.mjs +82 -0
  333. package/kits/hub-game/scripts/test-ballot.mjs +1008 -0
  334. package/kits/hub-game/scripts/test-ban-join.mjs +121 -13
  335. package/kits/hub-game/scripts/test-build.mjs +49 -0
  336. package/kits/hub-game/scripts/test-cells.mjs +71 -0
  337. package/kits/hub-game/scripts/test-chat.mjs +863 -0
  338. package/kits/hub-game/scripts/test-classic.mjs +2 -0
  339. package/kits/hub-game/scripts/test-companion-chat.mjs +216 -0
  340. package/kits/hub-game/scripts/test-companion-client.mjs +1167 -0
  341. package/kits/hub-game/scripts/test-companion.mjs +259 -0
  342. package/kits/hub-game/scripts/test-control-layout-dom.mjs +120 -0
  343. package/kits/hub-game/scripts/test-crowd-names.mjs +205 -0
  344. package/kits/hub-game/scripts/test-decor-client.mjs +344 -0
  345. package/kits/hub-game/scripts/test-decor.mjs +464 -0
  346. package/kits/hub-game/scripts/test-default-environment-root.mjs +95 -0
  347. package/kits/hub-game/scripts/test-default-environment.mjs +267 -0
  348. package/kits/hub-game/scripts/test-door-analytics.mjs +58 -0
  349. package/kits/hub-game/scripts/test-door-jump.mjs +100 -0
  350. package/kits/hub-game/scripts/test-earned-client.mjs +459 -0
  351. package/kits/hub-game/scripts/test-earned.mjs +1224 -0
  352. package/kits/hub-game/scripts/test-emote-bubble.mjs +110 -0
  353. package/kits/hub-game/scripts/test-far-avatars.mjs +340 -0
  354. package/kits/hub-game/scripts/test-fps-telemetry.mjs +112 -0
  355. package/kits/hub-game/scripts/test-frame-batch.mjs +252 -0
  356. package/kits/hub-game/scripts/test-fresh-friends.mjs +118 -0
  357. package/kits/hub-game/scripts/test-friend-bests.mjs +435 -0
  358. package/kits/hub-game/scripts/test-grab-orbit.mjs +961 -0
  359. package/kits/hub-game/scripts/test-grab.mjs +7 -0
  360. package/kits/hub-game/scripts/test-hats.mjs +422 -168
  361. package/kits/hub-game/scripts/test-high-only.mjs +170 -0
  362. package/kits/hub-game/scripts/test-hub-leaving.mjs +203 -0
  363. package/kits/hub-game/scripts/test-hub-ops.mjs +758 -2
  364. package/kits/hub-game/scripts/test-hub-trip.mjs +1594 -12
  365. package/kits/hub-game/scripts/test-hud-clear.mjs +484 -57
  366. package/kits/hub-game/scripts/test-hud-defects-dom.mjs +100 -0
  367. package/kits/hub-game/scripts/test-hud-rate.mjs +224 -0
  368. package/kits/hub-game/scripts/test-hud-safe-visibility-dom.mjs +83 -0
  369. package/kits/hub-game/scripts/test-idle.mjs +427 -1
  370. package/kits/hub-game/scripts/test-interest-cap.mjs +36 -0
  371. package/kits/hub-game/scripts/test-interest-cells.mjs +513 -0
  372. package/kits/hub-game/scripts/test-interest-client.mjs +118 -0
  373. package/kits/hub-game/scripts/test-interest.mjs +15 -0
  374. package/kits/hub-game/scripts/test-invites-client.mjs +430 -0
  375. package/kits/hub-game/scripts/test-invites.mjs +109 -0
  376. package/kits/hub-game/scripts/test-keys.mjs +46 -1
  377. package/kits/hub-game/scripts/test-labels.mjs +664 -0
  378. package/kits/hub-game/scripts/test-landscape-layout.mjs +194 -0
  379. package/kits/hub-game/scripts/test-list-scroll-dom.mjs +49 -0
  380. package/kits/hub-game/scripts/test-load-abandon.mjs +246 -0
  381. package/kits/hub-game/scripts/test-loading-cover.mjs +162 -0
  382. package/kits/hub-game/scripts/test-manifest.mjs +472 -0
  383. package/kits/hub-game/scripts/test-menu-client.mjs +585 -0
  384. package/kits/hub-game/scripts/test-menu.mjs +319 -0
  385. package/kits/hub-game/scripts/test-npcs.mjs +2528 -13
  386. package/kits/hub-game/scripts/test-object-entry.mjs +76 -0
  387. package/kits/hub-game/scripts/test-observed.mjs +745 -0
  388. package/kits/hub-game/scripts/test-pack.mjs +7 -0
  389. package/kits/hub-game/scripts/test-pad-cues.mjs +304 -0
  390. package/kits/hub-game/scripts/test-pad-occupancy.mjs +177 -0
  391. package/kits/hub-game/scripts/test-picker.mjs +541 -0
  392. package/kits/hub-game/scripts/test-placement-cache.mjs +690 -0
  393. package/kits/hub-game/scripts/test-progress-reset.mjs +559 -0
  394. package/kits/hub-game/scripts/test-push-visit.mjs +26 -0
  395. package/kits/hub-game/scripts/test-quality.mjs +385 -0
  396. package/kits/hub-game/scripts/test-rehello.mjs +1733 -0
  397. package/kits/hub-game/scripts/test-relations-among.mjs +222 -0
  398. package/kits/hub-game/scripts/test-relations-refresh.mjs +188 -0
  399. package/kits/hub-game/scripts/test-resume-action-order.mjs +598 -0
  400. package/kits/hub-game/scripts/test-resume-held.mjs +239 -0
  401. package/kits/hub-game/scripts/test-resume-pose.mjs +142 -0
  402. package/kits/hub-game/scripts/test-safe-events-dom.mjs +116 -0
  403. package/kits/hub-game/scripts/test-safe-layout.mjs +330 -0
  404. package/kits/hub-game/scripts/test-say.mjs +1 -1
  405. package/kits/hub-game/scripts/test-shot.mjs +901 -0
  406. package/kits/hub-game/scripts/test-signin-client.mjs +45 -0
  407. package/kits/hub-game/scripts/test-soundscape.mjs +5437 -0
  408. package/kits/hub-game/scripts/test-spin.mjs +314 -0
  409. package/kits/hub-game/scripts/test-standing.mjs +449 -0
  410. package/kits/hub-game/scripts/test-storage-limit.mjs +333 -0
  411. package/kits/hub-game/scripts/test-stuck.mjs +1904 -0
  412. package/kits/hub-game/scripts/test-talk-overlay-dom.mjs +130 -0
  413. package/kits/hub-game/scripts/test-tier-cells.mjs +706 -0
  414. package/kits/hub-game/scripts/test-tiers-render.mjs +412 -0
  415. package/kits/hub-game/scripts/test-tiers.mjs +476 -2
  416. package/kits/hub-game/scripts/test-toast-band.mjs +61 -0
  417. package/kits/hub-game/scripts/test-try-on.mjs +22 -22
  418. package/kits/hub-game/scripts/test-vis.mjs +770 -0
  419. package/kits/hub-game/scripts/test-visibility.mjs +134 -0
  420. package/kits/hub-game/scripts/test-weakest-tier.mjs +924 -0
  421. package/kits/hub-game/scripts/test-world-labels.mjs +367 -0
  422. package/kits/hub-game/scripts/test-yours-chrome.mjs +210 -0
  423. package/kits/hub-game/scripts/test-yours.mjs +403 -0
  424. package/kits/multiplayer-3d/CLAUDE.md +50 -0
  425. package/kits/multiplayer-3d/castle.json +5 -5
  426. package/kits/multiplayer-3d/code/client/avatars.js +7 -0
  427. package/kits/multiplayer-3d/code/client/gait.js +65 -0
  428. package/kits/multiplayer-3d/code/client/joinFailure.js +27 -0
  429. package/kits/multiplayer-3d/code/client/nameTags.js +59 -4
  430. package/kits/multiplayer-3d/code/client/resumeGate.js +139 -0
  431. package/kits/multiplayer-3d/code/options.js +5 -0
  432. package/kits/multiplayer-3d/code/server/ownership.js +10 -2
  433. package/kits/multiplayer-3d/code/server/sceneBodies.js +12 -0
  434. package/kits/multiplayer-3d/code/server/world.js +7 -0
  435. package/kits/multiplayer-3d/code/systems/multiplayer.js +443 -34
  436. package/kits/multiplayer-3d/package-lock.json +8 -1
  437. package/kits/multiplayer-3d/package.json +3 -1
  438. package/kits/multiplayer-3d/scripts/fixtures/README.md +11 -0
  439. package/kits/multiplayer-3d/scripts/fixtures/ownership-legacy.json +2 -0
  440. package/kits/multiplayer-3d/scripts/ownership-harness.mjs +102 -0
  441. package/kits/multiplayer-3d/scripts/ownership-loader.mjs +46 -0
  442. package/kits/multiplayer-3d/scripts/ownership-worker.mjs +15 -0
  443. package/kits/multiplayer-3d/scripts/record-ownership-session.mjs +98 -0
  444. package/kits/multiplayer-3d/scripts/test-eligible-claims.mjs +167 -0
  445. package/kits/multiplayer-3d/scripts/test-join-watchdog.mjs +436 -0
  446. package/kits/multiplayer-3d/scripts/test-own-name-tag.mjs +247 -0
  447. package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +624 -0
  448. package/kits/physics-2d/CLAUDE.md +19 -1
  449. package/kits/physics-2d/castle.json +2 -2
  450. package/kits/physics-2d/engine/frozenActors.js +233 -0
  451. package/kits/physics-2d/engine/scene.js +337 -3
  452. package/kits/physics-2d/engine/skyKey.js +129 -0
  453. package/kits/physics-2d/engine/stillClock.js +106 -0
  454. package/kits/physics-2d/engine/updateBudget.js +21 -0
  455. package/kits/physics-2d/eslint.config.js +1 -1
  456. package/kits/physics-2d/play/behaviors/AnalogStick.js +198 -0
  457. package/kits/physics-2d/play/behaviors/Camera.js +40 -0
  458. package/kits/physics-2d/play/behaviors/Collider.js +122 -0
  459. package/kits/physics-2d/play/behaviors/Draggable.js +115 -0
  460. package/kits/physics-2d/play/behaviors/Goal.js +46 -0
  461. package/kits/physics-2d/play/behaviors/Joints.js +126 -0
  462. package/kits/physics-2d/play/behaviors/Layout.js +71 -0
  463. package/kits/physics-2d/play/behaviors/RigidBody.js +57 -0
  464. package/kits/physics-2d/play/behaviors/Slingshot.js +142 -0
  465. package/kits/physics-2d/play/behaviors/SoundPlayer.js +263 -0
  466. package/kits/physics-2d/play/behaviors/Sprite.js +406 -0
  467. package/kits/physics-2d/play/behaviors/Style.js +209 -0
  468. package/kits/physics-2d/play/behaviors/Text.js +85 -0
  469. package/kits/physics-2d/play/behaviors/Video.js +93 -0
  470. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +326 -1
  471. package/kits/physics-3d/CLAUDE.md +42 -529
  472. package/kits/physics-3d/behaviors/Body.jsx +3 -0
  473. package/kits/physics-3d/behaviors/Model.jsx +3 -0
  474. package/kits/physics-3d/behaviors/Player.jsx +661 -87
  475. package/kits/physics-3d/behaviors/Shape.jsx +3 -0
  476. package/kits/physics-3d/behaviors/Solid.jsx +3 -0
  477. package/kits/physics-3d/behaviors/Transform.jsx +3 -0
  478. package/kits/physics-3d/castle.json +3 -3
  479. package/kits/physics-3d/docs/engine-camera.md +542 -0
  480. package/kits/physics-3d/docs/engine-frame-cap.md +136 -0
  481. package/kits/physics-3d/docs/engine-load.md +149 -0
  482. package/kits/physics-3d/docs/engine-look.md +114 -0
  483. package/kits/physics-3d/docs/engine-shadows.md +372 -0
  484. package/kits/physics-3d/docs/engine-skip-work.md +187 -0
  485. package/kits/physics-3d/docs/engine-sky.md +198 -0
  486. package/kits/physics-3d/docs/engine-static-actors.md +226 -0
  487. package/kits/physics-3d/docs/engine-view.md +37 -0
  488. package/kits/physics-3d/docs/pxmodel-format.md +9 -1
  489. package/kits/physics-3d/engine3d/PlayOnly3D.jsx +5 -1
  490. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +19 -277
  491. package/kits/physics-3d/engine3d/actornode.js +87 -0
  492. package/kits/physics-3d/engine3d/animationBudget.js +23 -0
  493. package/kits/physics-3d/engine3d/branches.js +3 -13
  494. package/kits/physics-3d/engine3d/cage.js +2 -7
  495. package/kits/physics-3d/engine3d/cageops.js +2 -17
  496. package/kits/physics-3d/engine3d/dataBehaviors.js +12 -0
  497. package/kits/physics-3d/engine3d/editorWorld.js +6 -0
  498. package/kits/physics-3d/engine3d/emptynodes.js +232 -0
  499. package/kits/physics-3d/engine3d/framecap.js +99 -0
  500. package/kits/physics-3d/engine3d/frozenphysics.js +140 -0
  501. package/kits/physics-3d/engine3d/frozenstatics.js +273 -0
  502. package/kits/physics-3d/engine3d/gait.js +126 -0
  503. package/kits/physics-3d/engine3d/initialModelFiles.js +18 -0
  504. package/kits/physics-3d/engine3d/kithooks.js +47 -0
  505. package/kits/physics-3d/engine3d/look.js +514 -48
  506. package/kits/physics-3d/engine3d/lookbake.js +208 -0
  507. package/kits/physics-3d/engine3d/materialpresets.js +2 -0
  508. package/kits/physics-3d/engine3d/modelFiles.js +3 -17
  509. package/kits/physics-3d/engine3d/modelMath.js +49 -0
  510. package/kits/physics-3d/engine3d/modelready.js +16 -0
  511. package/kits/physics-3d/engine3d/motion.js +39 -10
  512. package/kits/physics-3d/engine3d/nearshadows.js +106 -21
  513. package/kits/physics-3d/engine3d/optimize.js +9 -5
  514. package/kits/physics-3d/engine3d/orbitinput.js +522 -10
  515. package/kits/physics-3d/engine3d/orbitlens.js +48 -0
  516. package/kits/physics-3d/engine3d/ownmodel.js +213 -0
  517. package/kits/physics-3d/engine3d/partgeometry.js +1 -16
  518. package/kits/physics-3d/engine3d/paths.js +1 -9
  519. package/kits/physics-3d/engine3d/playTimings.js +50 -0
  520. package/kits/physics-3d/engine3d/playerRun.js +372 -0
  521. package/kits/physics-3d/engine3d/pxmodel.js +42 -11
  522. package/kits/physics-3d/engine3d/rapier.js +27 -0
  523. package/kits/physics-3d/engine3d/scatter.js +1 -11
  524. package/kits/physics-3d/engine3d/shadowfade.js +890 -0
  525. package/kits/physics-3d/engine3d/sky.js +547 -0
  526. package/kits/physics-3d/engine3d/skylife.js +306 -0
  527. package/kits/physics-3d/engine3d/squarefirst.js +177 -0
  528. package/kits/physics-3d/engine3d/stillshadows.js +399 -0
  529. package/kits/physics-3d/engine3d/sweep.js +1 -25
  530. package/kits/physics-3d/engine3d/unchanged.js +11 -0
  531. package/kits/physics-3d/engine3d/viewrange.js +52 -0
  532. package/kits/physics-3d/engine3d/world3d.js +1253 -76
  533. package/kits/physics-3d/eslint.config.js +2 -1
  534. package/kits/physics-3d/main.jsx +10 -2
  535. package/kits/physics-3d/package-lock.json +7 -0
  536. package/kits/physics-3d/package.json +5 -1
  537. package/kits/physics-3d/play/behaviors/Body.js +31 -0
  538. package/kits/physics-3d/play/behaviors/Door.js +37 -0
  539. package/kits/physics-3d/play/behaviors/Lookable.js +16 -0
  540. package/kits/physics-3d/play/behaviors/Model.js +23 -0
  541. package/kits/physics-3d/play/behaviors/Pickup.js +46 -0
  542. package/kits/physics-3d/play/behaviors/Player.js +1204 -0
  543. package/kits/physics-3d/play/behaviors/Shape.js +47 -0
  544. package/kits/physics-3d/play/behaviors/Solid.js +16 -0
  545. package/kits/physics-3d/play/behaviors/Transform.js +29 -0
  546. package/kits/physics-3d/pnpm-lock.yaml +8 -0
  547. package/kits/physics-3d/scripts/bench-shadow-fade.mjs +37 -0
  548. package/kits/physics-3d/scripts/build-rapier-gz.mjs +56 -0
  549. package/kits/physics-3d/scripts/frozen-statics-fixture.mjs +141 -0
  550. package/kits/physics-3d/scripts/look-baseline.mjs +155 -0
  551. package/kits/physics-3d/scripts/test-camera-follow.mjs +5 -1
  552. package/kits/physics-3d/scripts/test-camera-orbit.mjs +2613 -82
  553. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +2 -2
  554. package/kits/physics-3d/scripts/test-empty-gait-hints.mjs +89 -0
  555. package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +438 -0
  556. package/kits/physics-3d/scripts/test-frame-cap.mjs +452 -0
  557. package/kits/physics-3d/scripts/test-frozen-nested.mjs +49 -0
  558. package/kits/physics-3d/scripts/test-frozen-statics-legacy-physics2d.mjs +123 -0
  559. package/kits/physics-3d/scripts/test-frozen-statics.mjs +434 -0
  560. package/kits/physics-3d/scripts/test-gait.mjs +387 -0
  561. package/kits/physics-3d/scripts/test-look-bake.mjs +1056 -0
  562. package/kits/physics-3d/scripts/test-model-parse-cache.mjs +92 -0
  563. package/kits/physics-3d/scripts/test-near-shadows.mjs +5 -2
  564. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +2001 -0
  565. package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +582 -0
  566. package/kits/physics-3d/scripts/test-orbit-shot.mjs +657 -0
  567. package/kits/physics-3d/scripts/test-orbit-view.mjs +230 -0
  568. package/kits/physics-3d/scripts/test-rapier-gz.mjs +106 -0
  569. package/kits/physics-3d/scripts/test-skip-empty-nodes.mjs +845 -0
  570. package/kits/physics-3d/scripts/test-sky.mjs +2470 -0
  571. package/kits/physics-3d/scripts/test-square-first.mjs +921 -0
  572. package/kits/physics-3d/scripts/test-static-actors.mjs +10 -1
  573. package/kits/physics-3d/scripts/test-static-physics.mjs +4 -1
  574. package/kits/physics-3d/scripts/test-static-scenery.mjs +2174 -0
  575. package/kits/physics-3d/scripts/test-steady-hover.mjs +7 -2
  576. package/kits/physics-3d/scripts/test-still-shadows.mjs +477 -0
  577. package/kits/physics-3d/scripts/test-view-range.mjs +260 -0
  578. package/kits/physics-3d/systems/physics3d.js +419 -9
  579. package/kits/real-time/castle.json +2 -2
  580. package/kits/real-time/code/client/connection.js +33 -10
  581. package/kits/real-time/code/client/gameHooks.js +2 -0
  582. package/kits/real-time/code/client/joinOverlay.js +9 -4
  583. package/kits/real-time/code/server/gameHooks.js +7 -0
  584. package/kits/real-time/code/server/session.js +102 -22
  585. package/kits/real-time/package-lock.json +1 -1
  586. package/package.json +2 -2
  587. package/dist/shell/assets/index-Cf61cNfT.css +0 -1
@@ -53,7 +53,7 @@ function applyHover(phys, actor, t, dims, dt) {
53
53
  }
54
54
 
55
55
  // The hover of a scene that set `"engine": { "camera": { "follow": "rigid" } }`
56
- // (the kit's CLAUDE.md has the terms): the same spring, asked for as a force.
56
+ // (docs/engine-camera.md has the terms): the same spring, asked for as a force.
57
57
  // `applyHover` pushes once per drawn frame while gravity pulls once per fixed
58
58
  // physics step, and a frame takes none, one or two steps, so on a frame that
59
59
  // is not exactly one step the player is kicked up or let drop: a bob of a
@@ -149,8 +149,54 @@ function settle(value, from, to, dt) {
149
149
  return to - lag + (value - from + lag) * Math.exp(-FOLLOW_RATE * dt);
150
150
  }
151
151
 
152
+ // The follow camera of a scene that capped its frame rate (`"engine": {
153
+ // "maxFps": n }`, `scene.maxFps` above 0) and set no camera key: the camera
154
+ // `updateCamera` places, the same target and rate, placed differently.
155
+ // updateCamera eases once a frame by 1 - e^(-12 dt), from the update, toward
156
+ // where the player was drawn LAST frame: behind a target moving at v it trails
157
+ // by about v/12 + v dt/2, and the player is then drawn v dt further on. Both
158
+ // change with each frame's dt, and the cap hands frames of 25 to 50 ms on a
159
+ // slow phone, so the player would slide back and forth on screen as it walks.
160
+ // So under the cap the camera is placed as the rigid one is: at the end of
161
+ // the frame, by the physics system (`placeFollowCamera`), on the position the
162
+ // frame is drawn with, and each coordinate is eased as if the target moved
163
+ // steadily from last frame's place to this frame's (`settle`: the exact
164
+ // solution of x' = 12 (target - x)). A steady walk is then trailed by v/12
165
+ // whatever the frames; a target standing still is reached as the lerp
166
+ // reaches it. Last frame's target is on the actor's runtime (`camTarget`).
167
+ // Without the cap updateCamera runs as it always did.
168
+ function placeCapped(scene, id, dt) {
169
+ const actor = scene.getActor(id);
170
+ const t = actor?.components.Transform;
171
+ const props = actor?.components.Player;
172
+ const cam = scene.three?.camera;
173
+ if (!cam || !t || !props || props.$enabled === false) return;
174
+ const per = persistentOf(scene);
175
+ const rt = actor.runtime;
176
+ const target = {
177
+ x: t.x - props.camDistance * Math.sin(per.camAngle),
178
+ y: t.y + props.camHeight,
179
+ z: t.z + props.camDistance * Math.cos(per.camAngle),
180
+ };
181
+ const last = per.camLastAt;
182
+ const jumped = last && Math.hypot(t.x - last.x, t.z - last.z) > TELEPORT_PER_FRAME;
183
+ per.camLastAt = { x: t.x, z: t.z };
184
+ const from = rt.camTarget ?? target;
185
+ rt.camTarget = target;
186
+ if (jumped || Math.hypot(target.x - cam.position.x, target.z - cam.position.z) > 20) {
187
+ cam.position.set(target.x, target.y, target.z);
188
+ } else {
189
+ cam.position.set(
190
+ settle(cam.position.x, from.x, target.x, dt),
191
+ settle(cam.position.y, from.y, target.y, dt),
192
+ settle(cam.position.z, from.z, target.z, dt)
193
+ );
194
+ }
195
+ cam.lookAt(t.x, t.y + 0.5, t.z);
196
+ }
197
+
152
198
  // The follow camera of a scene that set `"engine": { "camera": { "follow":
153
- // "rigid" } }` (the kit's CLAUDE.md has the terms). It moves with the player
199
+ // "rigid" } }` (docs/engine-camera.md has the terms). It moves with the player
154
200
  // as one piece: the offset from the player (its angle and height) and the
155
201
  // player's height are eased, the player's ground position is not, so a steady
156
202
  // walk leaves the player at one place on screen whatever the frame lengths.
@@ -207,8 +253,8 @@ function placeFollowing(scene, id, dt) {
207
253
 
208
254
  // ---------------------------------------------------------------------------
209
255
  // The camera the player controls: a scene that set `"engine": { "camera": {
210
- // "follow": "rigid", "control": "orbit" } }` (the kit's CLAUDE.md has the
211
- // terms). Everything from here to `findLookText` runs under that key only,
256
+ // "follow": "rigid", "control": "orbit" } }` (docs/engine-camera.md has the
257
+ // terms). Everything from here to `hudContents` runs under that key only,
212
258
  // from the one branch at the top of `Player.update`; nothing above this line
213
259
  // calls into it. It restates the steps of `update` that it shares (the
214
260
  // persistent defaults, the jump, the fall, the hud) rather than have `update`
@@ -222,26 +268,92 @@ function placeFollowing(scene, id, dt) {
222
268
  // (`scene.cameraOrbit`), which a scene load does not replace, and never on
223
269
  // `scene.persistent`.
224
270
 
225
- // The camera looks at the player this far above its Transform.
226
- const LOOK_HEIGHT = 0.8;
227
- // The nearest and farthest the player can zoom, metres from that point. A
228
- // Player whose camDistance/camHeight start it outside these is given room to
229
- // where it starts.
230
- const ORBIT_NEAREST = 3;
231
- const ORBIT_FARTHEST = 12;
232
- // The lowest and highest the camera tilts, above the horizontal.
233
- const ORBIT_PITCH_LEAST = 5 * DEG;
234
- const ORBIT_PITCH_MOST = 70 * DEG;
271
+ // The numbers below are Roblox's default (Classic) third-person camera at
272
+ // our scale. A Roblox character is 5 studs tall; ours, the kit's
273
+ // player.pxmodel standing on its 1.4 m capsule (the hub's avatar), is 1.46 m
274
+ // from the soles of its feet (0.02 m above the model's origin) to the top of
275
+ // its cap (1.48 m), so one stud is 1.46 / 5 = 0.292 m here.
276
+ const STUD = 1.46 / 5;
277
+ // The camera looks at the player this far above its Transform. Roblox looks
278
+ // at the root part plus 1.5 studs; the root part is the torso's middle, and
279
+ // so is our Transform (the capsule's middle, 0.70 m above the model's origin,
280
+ // where the torso's middle is 0.69), so the same 1.5 studs: 0.438 m, the neck.
281
+ const LOOK_HEIGHT = 1.5 * STUD;
282
+ // How far from that point the camera starts: Roblox's 12.5 studs, 3.65 m,
283
+ // the same two and a half character heights.
284
+ const ORBIT_START = 12.5 * STUD;
285
+ // The nearest and farthest the player can zoom, metres from that point.
286
+ // Roblox lets the player in to 0.5 studs, which is first person; here the
287
+ // nearest keeps the camera clear of the character, which an avatar hides
288
+ // itself from within about 1 m. The farthest is Roblox's 128 studs, 37.4 m.
289
+ const ORBIT_NEAREST = 1.5;
290
+ const ORBIT_FARTHEST = 128 * STUD;
291
+ // The lowest and highest the camera tilts, above the horizontal: Roblox's 80
292
+ // degrees either way. Below the horizontal the camera is lower than the point
293
+ // it looks at, looking up, and the ground (a fixed solid, as walls are) holds
294
+ // it above itself as a wall holds it in front (`limitReach`, `sweep`).
295
+ const ORBIT_PITCH_LEAST = -80 * DEG;
296
+ const ORBIT_PITCH_MOST = 80 * DEG;
297
+ // The tilt the camera starts at, whatever the Player's camDistance and
298
+ // camHeight: 15 degrees down, behind the player, as Roblox starts. With the
299
+ // 70 degree lens (engine3d/orbitlens.js `fitOrbitLens`) the top of the frame
300
+ // is 20 degrees above the horizon: a world's sky shows.
301
+ const ORBIT_PITCH_START = 15 * DEG;
235
302
  // How fast the camera's angle, tilt and distance catch up with what was
236
303
  // asked: quick enough to feel direct, slow enough to take the steps out of a
237
304
  // finger's drag.
238
305
  const ORBIT_RATE = 20;
239
306
  // How fast the character turns to face the way it walks.
240
307
  const FACE_RATE = 12;
241
- // The camera stays this far in front of what is between it and the player,
242
- // and no nearer the point it looks at than CAMERA_NEAREST.
308
+ // The camera stays at least this far off every fixed surface: it is a ball
309
+ // of this radius swept out from the point it looks at (`sweep`), so it is
310
+ // this far off whatever stops it, square to the surface, however the line
311
+ // meets it (a wall met at a grazing angle, a box's edge or corner, the
312
+ // ground seen along at a low angle). A wider lens than the default's needs
313
+ // more: the lens's near plane must stay clear of the surface whichever way
314
+ // the camera looks, so the margin is the distance from the camera to the
315
+ // near plane's corners plus LENS_CLEARANCE when that is more
316
+ // (`lensMargin`). At the default 70 degrees on a 20:9 screen the corners
317
+ // are 0.198 m off and the margin is 0.25 m; at 120 degrees on 20:9, 0.484 m.
243
318
  const CAMERA_MARGIN = 0.25;
319
+ const LENS_CLEARANCE = 0.05;
320
+ // A look point nearer fixed surfaces than the margin and START_SKIN (a
321
+ // player pressed against a wall, or in a corner, with a wide lens) has the
322
+ // ball start moved the least way that puts it that far off all of them
323
+ // together (`findStart`), and looked around again, START_TRIES times at
324
+ // most; a point within START_SETTLED of that distance is taken. A gap too
325
+ // narrow for that leaves the ball smaller, down to START_LEAST.
326
+ const START_SKIN = 0.05;
327
+ const START_TRIES = 8;
328
+ const START_SETTLED = 1e-4;
329
+ const START_LEAST = 0.02;
330
+ // Where no start is found at all (the look point inside a solid) the camera
331
+ // is held by a ray alone, as it was before the ball (`onRay`): a margin
332
+ // short of the hit, no nearer the look point than CAMERA_NEAREST, but never
333
+ // past a real surface: then SURFACE_GAP short of it.
244
334
  const CAMERA_NEAREST = 0.6;
335
+ const SURFACE_GAP = 0.01;
336
+ // The lens the orbit camera is drawn with (world3d.js `orbitFov`, which sets
337
+ // it on the camera at the draw that follows this placement): the scene's
338
+ // `engine.camera.fov`, 10 to 120 degrees, else 70.
339
+ const ORBIT_FOV = 70;
340
+ function orbitFov(scene) {
341
+ const fov = scene.data?.engine?.camera?.fov;
342
+ return typeof fov === 'number' && fov >= 10 && fov <= 120 ? fov : ORBIT_FOV;
343
+ }
344
+ // The margin for this frame's lens: CAMERA_MARGIN, or the near plane's
345
+ // corners' distance from the camera, near * sqrt(1 + tan^2(v/2) +
346
+ // (aspect tan(v/2))^2), plus LENS_CLEARANCE, whichever is more. A point of
347
+ // the near plane is no farther from the camera than its corners, so a camera
348
+ // that far off a surface, square to it, has the whole near plane in front of
349
+ // it.
350
+ function lensMargin(scene, cam) {
351
+ const near = Number.isFinite(cam.near) && cam.near > 0 ? cam.near : 0.1;
352
+ const aspect = Number.isFinite(cam.aspect) && cam.aspect > 0 ? cam.aspect : 1;
353
+ const half = Math.tan((orbitFov(scene) * DEG) / 2);
354
+ const corner = near * Math.sqrt(1 + half * half + aspect * half * (aspect * half));
355
+ return Math.max(CAMERA_MARGIN, corner + LENS_CLEARANCE);
356
+ }
245
357
  // How fast the camera moves back out once nothing is in the way.
246
358
  const CAMERA_OUT_RATE = 6;
247
359
  // Within this of the distance it wants, a camera let back out is let go.
@@ -249,11 +361,16 @@ const CAMERA_OUT_DONE = 1e-4;
249
361
  // A camera something else placed is eased on from where it was left at this
250
362
  // rate: a twentieth of the way is left after 0.3 s.
251
363
  const TAKEOVER_RATE = 10;
364
+ // A settled shot uses its exact authored pose, avoiding round-trip drift.
365
+ const SHOT_SETTLED = 1e-10;
366
+ // Stay off the poles, where lookAt cannot retain the shot's azimuth.
367
+ const SHOT_PITCH_LIMIT = 89 * DEG;
368
+ const SHOT_YAW_EPS = 1e-8;
252
369
  // The camera was placed on the frame before this one when the scene time it
253
370
  // was last placed at is this frame's length ago, to within this (seconds).
254
371
  const PLACED_WITHIN = 1e-6;
255
372
  // A takeover blend farther than this from the camera's place has its drawn
256
- // point tested for collision too (a second ray, only while it lasts).
373
+ // point tested for collision too (a second sweep, only while it lasts).
257
374
  const BLEND_TESTED = 1e-4;
258
375
 
259
376
  const clamp = (value, least, most) => Math.max(least, Math.min(most, value));
@@ -279,13 +396,15 @@ function persistentOf(scene) {
279
396
  // This frame's walk: a direction on the ground no longer than 1, or null
280
397
  // standing still. W/S and up/down walk away from and toward the camera, A/D
281
398
  // strafe, the stick does both by how far it is pushed; left/right swing the
282
- // camera at `turnSpeed`. The character's facing eases toward the walk and
283
- // stays put standing still.
399
+ // camera at `turnSpeed`. Under a held shot the camera cannot swing, so
400
+ // left/right strafe like A/D instead. The character's facing eases toward
401
+ // the walk and stays put standing still.
284
402
  function driveOrbiting(scene, per, rt, props, dt) {
285
403
  const keys = scene.keys;
286
- per.camAngle += held(keys, ['ArrowRight'], ['ArrowLeft']) * props.turnSpeed * dt;
404
+ const shot = validOrbitShot(scene.orbitShot);
405
+ if (!shot) per.camAngle += held(keys, ['ArrowRight'], ['ArrowLeft']) * props.turnSpeed * dt;
287
406
  let ahead = held(keys, ['KeyW', 'ArrowUp'], ['KeyS', 'ArrowDown']);
288
- let aside = held(keys, ['KeyD'], ['KeyA']);
407
+ let aside = shot ? held(keys, ['KeyD', 'ArrowRight'], ['KeyA', 'ArrowLeft']) : held(keys, ['KeyD'], ['KeyA']);
289
408
  const stick = scene.moveInput;
290
409
  if (ahead === 0 && aside === 0 && stick?.active && Math.hypot(stick.x, stick.y) >= 0.15) {
291
410
  ahead = -stick.y;
@@ -294,8 +413,14 @@ function driveOrbiting(scene, per, rt, props, dt) {
294
413
  const length = Math.hypot(ahead, aside);
295
414
  if (length === 0) return null;
296
415
  const scale = length > 1 ? 1 / length : 1;
297
- const sin = Math.sin(per.camAngle);
298
- const cos = Math.cos(per.camAngle);
416
+ // Keep the persistent follow heading while walking in the held view's
417
+ // drawn direction, including its takeover blend. Before placement, use
418
+ // the shot's target yaw.
419
+ const yaw = shot && scene.data?.engine?.camera?.walkFromShot === true
420
+ ? (rt.orbitShot?.active && Number.isFinite(rt.orbitShot.yaw) ? rt.orbitShot.yaw : shot.yaw * DEG)
421
+ : per.camAngle;
422
+ const sin = Math.sin(yaw);
423
+ const cos = Math.cos(yaw);
299
424
  const move = { x: (sin * ahead + cos * aside) * scale, z: (sin * aside - cos * ahead) * scale };
300
425
  rt.facing += arc(Math.atan2(move.x, move.z) - rt.facing) * eased(FACE_RATE, dt);
301
426
  return move;
@@ -316,11 +441,11 @@ function jumpOrbiting(phys, actor, scene, rt, grounded, jumpSpeed, dt) {
316
441
  }
317
442
 
318
443
  function hudOrbiting(scene, actor, t, per, facing) {
319
- const left = scene.actorsWith('Pickup').length;
444
+ const { remaining: left, look } = hudContents(scene, actor, t, facing);
320
445
  const all = per.score + left;
321
446
  let score = '';
322
447
  if (all !== 0) score = left === 0 ? '◆ all shards found' : `◆ ${per.score}/${all}`;
323
- scene.hud = { score, look: findLookText(scene, actor, t, facing) };
448
+ scene.hud = { score, look };
324
449
  }
325
450
 
326
451
  // `Player.update` under the key.
@@ -356,23 +481,34 @@ function updateOrbiting(actor, scene, props, dt) {
356
481
 
357
482
  const finiteOr = (value, otherwise) => (Number.isFinite(value) ? value : otherwise);
358
483
 
359
- // The tilt and distance the player has chosen, on the runtime. They start
360
- // where the Player's camDistance and camHeight put the fixed camera, and
361
- // start there again for a Player with other numbers.
484
+ // The tilt and distance the player has chosen, on the runtime: they start
485
+ // at the scene's starting pitch and distance (or the defaults), and start
486
+ // again when those keys or camDistance/camHeight change. The latter two
487
+ // ask for a fresh camera but do not set its orbit distance or pitch.
362
488
  function orbitChoice(scene, props) {
363
489
  const distance = finiteOr(props.camDistance, 9);
364
490
  const height = finiteOr(props.camHeight, 7);
491
+ // Only a finite number is a start; anything else is the default, so a
492
+ // copy of the same scene data (a fresh {} included) never restarts it.
493
+ const startDistance = finiteOr(scene.data?.engine?.camera?.distance, undefined);
494
+ const startPitch = finiteOr(scene.data?.engine?.camera?.pitch, undefined);
495
+ const minPitch = finiteOr(scene.data?.engine?.camera?.minPitch, undefined);
496
+ const least = clamp(finiteOr(minPitch, -80) * DEG, ORBIT_PITCH_LEAST, ORBIT_PITCH_MOST);
365
497
  const chosen = scene.cameraOrbit;
366
- if (chosen && chosen.distance === distance && chosen.height === height) return chosen;
367
- const rise = height - LOOK_HEIGHT;
368
- const range = Math.max(CAMERA_NEAREST, Math.hypot(distance, rise));
498
+ if (chosen && chosen.distance === distance && chosen.height === height
499
+ && Object.is(chosen.startDistance, startDistance) && Object.is(chosen.startPitch, startPitch)
500
+ && Object.is(chosen.minPitch, minPitch)) return chosen;
369
501
  scene.cameraOrbit = {
370
502
  distance,
371
503
  height,
372
- range,
373
- pitch: clamp(Math.atan2(rise, distance), ORBIT_PITCH_LEAST, ORBIT_PITCH_MOST),
374
- nearest: Math.min(ORBIT_NEAREST, range),
375
- farthest: Math.max(ORBIT_FARTHEST, range),
504
+ startDistance,
505
+ startPitch,
506
+ minPitch,
507
+ least,
508
+ range: clamp(finiteOr(startDistance, ORBIT_START), ORBIT_NEAREST, ORBIT_FARTHEST),
509
+ pitch: clamp(Number.isFinite(startPitch) ? startPitch * DEG : ORBIT_PITCH_START, least, ORBIT_PITCH_MOST),
510
+ nearest: ORBIT_NEAREST,
511
+ farthest: ORBIT_FARTHEST,
376
512
  };
377
513
  return scene.cameraOrbit;
378
514
  }
@@ -380,7 +516,7 @@ function orbitChoice(scene, props) {
380
516
  // What the player asked of the camera this frame, onto what it is aimed for.
381
517
  function steerOrbit(per, chosen, look) {
382
518
  per.camAngle += look.yaw;
383
- chosen.pitch = clamp(chosen.pitch + look.pitch, ORBIT_PITCH_LEAST, ORBIT_PITCH_MOST);
519
+ chosen.pitch = clamp(chosen.pitch + look.pitch, chosen.least, ORBIT_PITCH_MOST);
384
520
  chosen.range = clamp(chosen.range * look.zoom, chosen.nearest, chosen.farthest);
385
521
  }
386
522
 
@@ -388,24 +524,245 @@ function steerOrbit(per, chosen, look) {
388
524
  // placed from) toward where it wants to be: a unit direction.
389
525
  const ray = { from: { x: 0, y: 0, z: 0 }, dir: { x: 0, y: 0, z: 0 } };
390
526
 
391
- // The farthest the camera may be along `ray` (`state.limit`, +Infinity when
392
- // nothing holds it): CAMERA_MARGIN in front of the nearest fixed solid within
393
- // its distance (and the margin past it), never nearer than CAMERA_NEAREST. A nearer limit is taken at
394
- // once; a farther one, or none, is eased out to at CAMERA_OUT_RATE, and once
395
- // the camera is back at its distance it is let go. Not asked while physics
396
- // has no world.
397
- function limitReach(phys, state, dt) {
398
- if (!phys?.castRayFixed || !phys.ready()) return;
399
- const hit = phys.castRayFixed(ray.from, ray.dir, state.range + CAMERA_MARGIN);
400
- const wall = hit ? Math.max(CAMERA_NEAREST, hit.distance - CAMERA_MARGIN) : Infinity;
401
- if (wall <= state.limit) {
402
- state.limit = wall;
527
+ // Whether this frame's camera collides: a physics world, and an api with the
528
+ // lens's queries (systems/physics3d.js `castBallFixed`, `nearFixed`,
529
+ // `castRayFixedNormal`).
530
+ const collides = (phys) => Boolean(phys?.castBallFixed && phys.nearFixed && phys.castRayFixedNormal && phys.ready());
531
+
532
+ // Where the camera's ball is swept from this frame (`findStart`), and its
533
+ // radius: the look point (`ray.from`) and the margin, or, near surfaces, a
534
+ // point moved off them (and, in a gap narrower than twice the margin, a
535
+ // smaller ball). `clear` is false when no start was found; then it is the
536
+ // look point and the camera is held by a ray alone (`sweep`).
537
+ const start = { x: 0, y: 0, z: 0, radius: 0, clear: true };
538
+
539
+ // The ball must start clear of everything (rapier does not answer a ball
540
+ // that starts touching a solid reliably). Every fixed surface within the
541
+ // radius and START_SKIN of the start (`nearFixed`) gives a plane touching
542
+ // its solid at its nearest point, with all of a convex solid behind it; the
543
+ // start is the look point moved the least way that puts it that far in
544
+ // front of every plane found so far, all together (`leastMove`), so in a
545
+ // corner the moves do not undo each other; then it is looked around again,
546
+ // until nothing is that near. Each plane keeps the ball off its solid, so
547
+ // planes found from earlier places still hold. The move grows from nothing
548
+ // as the look point comes nearer, so the camera does not jump. Where no
549
+ // place is that far off every plane (a gap narrower than twice the radius)
550
+ // the place that falls least short is taken with the ball made that much
551
+ // smaller, no smaller than START_LEAST. Then the camera point stays out of
552
+ // the walls but the lens does not: its near plane cuts into them (accepted,
553
+ // as Roblox's camera clips there; the near plane is not shrunk). One query
554
+ // in the open; two by a wall or in a corner.
555
+ function findStart(phys, margin) {
556
+ start.x = ray.from.x;
557
+ start.y = ray.from.y;
558
+ start.z = ray.from.z;
559
+ start.radius = margin;
560
+ start.clear = true;
561
+ if (!collides(phys)) return;
562
+ planes.length = 0;
563
+ let radius = margin;
564
+ for (let i = 0; i < START_TRIES; i += 1) {
565
+ const near = phys.nearFixed(start, radius + START_SKIN);
566
+ let closest = Infinity;
567
+ for (const n of near) {
568
+ if (n.inside || !n.normal || !(n.distance >= 0)) return giveUpStart();
569
+ closest = Math.min(closest, n.distance);
570
+ }
571
+ if (closest >= radius + START_SKIN - START_SETTLED) {
572
+ start.radius = radius;
573
+ return;
574
+ }
575
+ for (const n of near) if (n.distance < radius + START_SKIN - START_SETTLED) addPlane(n);
576
+ const move = leastMove(radius + START_SKIN);
577
+ if (move.short > 0) radius -= move.short;
578
+ if (!(radius >= START_LEAST)) return giveUpStart();
579
+ start.x = ray.from.x + move.x;
580
+ start.y = ray.from.y + move.y;
581
+ start.z = ray.from.z + move.z;
582
+ }
583
+ return giveUpStart();
584
+ }
585
+ function giveUpStart() {
586
+ start.x = ray.from.x;
587
+ start.y = ray.from.y;
588
+ start.z = ray.from.z;
589
+ start.clear = false;
590
+ }
591
+
592
+ // The planes `findStart` has found this frame: a unit normal facing the
593
+ // look point's side and the offset along it (n . p = d on the plane).
594
+ const planes = [];
595
+ const MOST_PLANES = 12;
596
+ function addPlane(near) {
597
+ const n = near.normal;
598
+ const d = n.x * near.point.x + n.y * near.point.y + n.z * near.point.z;
599
+ if (!Number.isFinite(d) || planes.length >= MOST_PLANES) return;
600
+ for (const p of planes) if (p.x * n.x + p.y * n.y + p.z * n.z > 1 - 1e-9 && Math.abs(p.d - d) < 1e-6) return;
601
+ planes.push({ x: n.x, y: n.y, z: n.z, d });
602
+ }
603
+
604
+ // The least move from the look point that leaves it `gap` or more in front
605
+ // of every plane: the nearest point of the intersection of their
606
+ // half-spaces, which lies on at most three of the planes, so it is the
607
+ // nearest of the moves onto each set of up to three that clears them all.
608
+ // When none does, the one that falls least short (`short`, how much).
609
+ const best = { x: 0, y: 0, z: 0, short: 0 };
610
+ const trial = { x: 0, y: 0, z: 0 };
611
+ const want = [];
612
+ function leastMove(gap) {
613
+ const at = ray.from;
614
+ want.length = 0;
615
+ for (const p of planes) want.push(gap - (p.x * at.x + p.y * at.y + p.z * at.z - p.d));
616
+ let bestShort = Infinity;
617
+ let bestLength = Infinity;
618
+ const consider = () => {
619
+ let short = 0;
620
+ for (let i = 0; i < planes.length; i += 1) {
621
+ const p = planes[i];
622
+ short = Math.max(short, want[i] - (p.x * trial.x + p.y * trial.y + p.z * trial.z));
623
+ }
624
+ const length = Math.hypot(trial.x, trial.y, trial.z);
625
+ const fits = short <= 1e-9;
626
+ const bestFits = bestShort <= 1e-9;
627
+ if ((fits && (!bestFits || length < bestLength)) || (!fits && !bestFits && (short < bestShort - 1e-12 || (short <= bestShort + 1e-12 && length < bestLength)))) {
628
+ bestShort = short;
629
+ bestLength = length;
630
+ best.x = trial.x;
631
+ best.y = trial.y;
632
+ best.z = trial.z;
633
+ }
634
+ };
635
+ trial.x = 0;
636
+ trial.y = 0;
637
+ trial.z = 0;
638
+ consider();
639
+ const n = planes.length;
640
+ for (let i = 0; i < n; i += 1) {
641
+ const a = planes[i];
642
+ trial.x = a.x * want[i];
643
+ trial.y = a.y * want[i];
644
+ trial.z = a.z * want[i];
645
+ consider();
646
+ for (let j = i + 1; j < n; j += 1) {
647
+ const b = planes[j];
648
+ const c = a.x * b.x + a.y * b.y + a.z * b.z;
649
+ const det = 1 - c * c;
650
+ if (det > 1e-9) {
651
+ const s = (want[i] - c * want[j]) / det;
652
+ const t = (want[j] - c * want[i]) / det;
653
+ trial.x = a.x * s + b.x * t;
654
+ trial.y = a.y * s + b.y * t;
655
+ trial.z = a.z * s + b.z * t;
656
+ consider();
657
+ }
658
+ for (let k = j + 1; k < n; k += 1) {
659
+ const e = planes[k];
660
+ // Cramer's rule on the rows a, b, e.
661
+ const bxeX = b.y * e.z - b.z * e.y;
662
+ const bxeY = b.z * e.x - b.x * e.z;
663
+ const bxeZ = b.x * e.y - b.y * e.x;
664
+ const exaX = e.y * a.z - e.z * a.y;
665
+ const exaY = e.z * a.x - e.x * a.z;
666
+ const exaZ = e.x * a.y - e.y * a.x;
667
+ const axbX = a.y * b.z - a.z * b.y;
668
+ const axbY = a.z * b.x - a.x * b.z;
669
+ const axbZ = a.x * b.y - a.y * b.x;
670
+ const det3 = a.x * bxeX + a.y * bxeY + a.z * bxeZ;
671
+ if (Math.abs(det3) <= 1e-9) continue;
672
+ trial.x = (want[i] * bxeX + want[j] * exaX + want[k] * axbX) / det3;
673
+ trial.y = (want[i] * bxeY + want[j] * exaY + want[k] * axbY) / det3;
674
+ trial.z = (want[i] * bxeZ + want[j] * exaZ + want[k] * axbZ) / det3;
675
+ consider();
676
+ }
677
+ }
678
+ }
679
+ best.short = bestShort <= 1e-9 ? 0 : bestShort;
680
+ return best;
681
+ }
682
+
683
+ // The farthest the camera may be along a ray that met `hit`, when it is held
684
+ // by a ray alone: the margin short of it, never nearer than CAMERA_NEAREST,
685
+ // except that a hit with a normal (a real surface: systems/physics3d.js
686
+ // `castRayFixedNormal`) is never passed: then no farther than SURFACE_GAP
687
+ // short of it.
688
+ function onRay(hit, margin) {
689
+ const most = Math.max(CAMERA_NEAREST, hit.distance - margin);
690
+ return hit.normal ? Math.min(most, Math.max(0, hit.distance - SURFACE_GAP)) : most;
691
+ }
692
+
693
+ // How far from `start` along the unit `dir` the camera may be, looking no
694
+ // farther than `length`: where a ball of `start.radius` (the margin, but in
695
+ // a gap too narrow for it) swept that way first touches a fixed solid (its
696
+ // time of impact), or +Infinity when it touches nothing. The camera there
697
+ // is that far off what stopped it and off everything it passed, so the
698
+ // whole near plane is in front of every surface, at any angle. Without a
699
+ // start, `onRay` of a ray from the look point. One query.
700
+ function sweep(phys, dir, length, margin) {
701
+ if (start.clear) {
702
+ const hit = phys.castBallFixed(start, dir, length, start.radius);
703
+ return hit ? Math.max(0, hit.distance) : Infinity;
704
+ }
705
+ const hit = phys.castRayFixedNormal(start, dir, length + margin);
706
+ return hit ? onRay(hit, margin) : Infinity;
707
+ }
708
+
709
+ // The farthest the camera may be along `ray` from `start` (`state.limit`,
710
+ // +Infinity when nothing holds it), Roblox's Popper: the sweep toward where
711
+ // the camera wants to be (its distance), each frame. A nearer limit is taken
712
+ // at once; a farther one, or none, is eased out to at CAMERA_OUT_RATE, never
713
+ // past what this frame's sweep touched, and once the camera is back at its
714
+ // distance it is let go. The ease is measured from the look point, from how
715
+ // far from it the camera was drawn last frame (`state.out`), not along this
716
+ // frame's ray: the start moves as the player nears or leaves a wall, so a
717
+ // limit along the ray from last frame's start is not where the camera was
718
+ // (review 7: a wall 0.5 m off removed let the camera out 1.161 m in a frame
719
+ // where easing allows 1.139). And it eases whatever drew the camera short of
720
+ // its distance, a start moved off a wall too, not only a sweep that held it
721
+ // (review 8: a box beside the look point removed let it out 0.062 m where
722
+ // 0.006 m is allowed); only a zoom moves it at its own pace. The camera is drawn at the nearer of its
723
+ // distance and the limit, so an easing camera never passes what the sweep
724
+ // touches. Not asked while physics has no world.
725
+ // Queries a frame: one `nearFixed` in the open, two by a wall or in a corner
726
+ // (START_TRIES at most), and one sweep, one more while a takeover blend
727
+ // lasts (`holdBlend`). A sweep is three rapier queries as a rule and 25 at
728
+ // most (systems/physics3d.js `castBallFixed`). As a rule 4 in the open and 5
729
+ // by a wall; at most 8 + 2 * 25 = 58 (a blend, a slanted corner, and rapier
730
+ // missing solids in both sweeps). None without a world.
731
+ function limitReach(phys, state, margin, dt) {
732
+ findStart(phys, margin);
733
+ if (!collides(phys)) return;
734
+ const was = state.out;
735
+ // A camera just placed: where the sweep allows, at once.
736
+ if (!Number.isFinite(was) || !Number.isFinite(state.outRange)) {
737
+ state.limit = sweep(phys, ray.dir, state.range, margin);
403
738
  return;
404
739
  }
405
- // Out from where the camera is, not from a limit past its distance.
406
- const from = Math.min(state.limit, state.range);
407
- state.limit = from + (Math.min(wall, state.range) - from) * eased(CAMERA_OUT_RATE, dt);
408
- if (wall === Infinity && state.limit >= state.range - CAMERA_OUT_DONE) state.limit = Infinity;
740
+ // How far short of its distance it was drawn last frame (held by a wall,
741
+ // or its start moved off one), eased away at CAMERA_OUT_RATE; and the
742
+ // distance itself as the player zooms, at the zoom's own pace. So it is
743
+ // let out at 6/s whatever drew it short, and a nearer wall takes it in at
744
+ // once. Along this frame's ray from this frame's start. The ball is swept
745
+ // only as far as the camera will be drawn, so the place drawn is the
746
+ // place the sweep checked (`castBallFixed` confirms its end is clear).
747
+ // (Zoomed in since, it is short of no more than the new distance.)
748
+ const short = Math.max(0, Math.min(state.outRange, state.range) - was);
749
+ const free = short <= CAMERA_OUT_DONE;
750
+ const letOut = free ? Infinity : alongRay(state.range - short * (1 - eased(CAMERA_OUT_RATE, dt)));
751
+ const wall = sweep(phys, ray.dir, Math.min(state.range, letOut), margin);
752
+ state.limit = free && wall === Infinity ? Infinity : Math.min(wall, letOut);
753
+ }
754
+
755
+ // How far along `ray` (or the unit `dir`) from `start` the camera is `out`
756
+ // from the look point
757
+ // (the farther place, where it moves away from the look point); the place
758
+ // nearest the look point when none is that far.
759
+ function alongRay(out, dir = ray.dir) {
760
+ const sx = start.x - ray.from.x;
761
+ const sy = start.y - ray.from.y;
762
+ const sz = start.z - ray.from.z;
763
+ const ahead = sx * dir.x + sy * dir.y + sz * dir.z;
764
+ const square = ahead * ahead - (sx * sx + sy * sy + sz * sz) + out * out;
765
+ return Math.max(0, -ahead + Math.sqrt(Math.max(0, square)));
409
766
  }
410
767
 
411
768
  // How far from its place (x, y, z) the camera is drawn this frame: nothing,
@@ -427,28 +784,178 @@ function takenOver(off, at, x, y, z, mine, jumped, dt) {
427
784
  }
428
785
 
429
786
  // The point drawn while a takeover blend lasts (its place plus `off`) is
430
- // collided as its place is: if a fixed solid lies between the look point
431
- // (`ray.from`) and it, it is pulled in along its own ray to CAMERA_MARGIN
432
- // in front (never nearer than CAMERA_NEAREST), and the pull is kept in
433
- // `off`, so the next frame eases on from where it was drawn.
787
+ // collided as its place is: swept toward from `start`, and if the ball
788
+ // touches a fixed solid short of it, it is pulled in along that line to
789
+ // where the ball stopped, and the pull is kept in `off`, so the next frame
790
+ // eases on from where it was drawn. One more query, only while it lasts.
791
+ // Returns whether it was pulled in.
434
792
  const drawn = { x: 0, y: 0, z: 0 };
435
793
 
436
- function holdBlend(phys, off, x, y, z) {
437
- if (!phys?.castRayFixed || !phys.ready()) return;
438
- drawn.x = x + off.x - ray.from.x;
439
- drawn.y = y + off.y - ray.from.y;
440
- drawn.z = z + off.z - ray.from.z;
794
+ function holdBlend(phys, off, x, y, z, margin) {
795
+ if (!collides(phys)) return;
796
+ drawn.x = x + off.x - start.x;
797
+ drawn.y = y + off.y - start.y;
798
+ drawn.z = z + off.z - start.z;
441
799
  const length = Math.hypot(drawn.x, drawn.y, drawn.z);
442
- if (!(length > CAMERA_NEAREST)) return;
800
+ if (!(length > 0)) return false;
443
801
  drawn.x /= length;
444
802
  drawn.y /= length;
445
803
  drawn.z /= length;
446
- const hit = phys.castRayFixed(ray.from, drawn, length + CAMERA_MARGIN);
447
- const most = hit ? Math.max(CAMERA_NEAREST, hit.distance - CAMERA_MARGIN) : Infinity;
448
- if (most >= length) return;
449
- off.x = ray.from.x + drawn.x * most - x;
450
- off.y = ray.from.y + drawn.y * most - y;
451
- off.z = ray.from.z + drawn.z * most - z;
804
+ const most = sweep(phys, drawn, length, margin);
805
+ if (most >= length) return false;
806
+ off.x = start.x + drawn.x * most - x;
807
+ off.y = start.y + drawn.y * most - y;
808
+ off.z = start.z + drawn.z * most - z;
809
+ return true;
810
+ }
811
+
812
+ // While a takeover blend lasts: a blend held in last frame is let out at
813
+ // the collision pace (`easeBlendOut`), and the point drawn is collided
814
+ // (`holdBlend`). Whether a wall has held it in, this frame or before in
815
+ // this blend: from then on, to the blend's end, it is let out at the
816
+ // collision pace.
817
+ function blendHeldIn(phys, state, off, x, y, z, margin, dt) {
818
+ const was = state.blendHeld === true && Number.isFinite(state.drawnOut);
819
+ if (was) easeBlendOut(state, off, x, y, z, dt);
820
+ return holdBlend(phys, off, x, y, z, margin) || was;
821
+ }
822
+
823
+ // A blend a wall held in (`holdBlend`, last frame) is let back out at the
824
+ // collision pace, not the blend's: no farther from the look point than
825
+ // easing at CAMERA_OUT_RATE from where it was drawn (`state.drawnOut`)
826
+ // toward where the camera rests this frame (review 10: not its distance,
827
+ // which a start moved off a wall can leave short of the place, holding the
828
+ // blend open for good), as `limitReach` lets its place out, so a
829
+ // wall that goes does not let the blend's TAKEOVER_RATE carry it out
830
+ // (review 9: 0.246 m in a frame where 0.179 m is allowed). Pulled in along
831
+ // its own line from `start`, and the pull kept in `off`. A blend whose own
832
+ // point is no farther than that goes on at its own pace. Returns whether it
833
+ // was held.
834
+ const blendDir = { x: 0, y: 0, z: 0 };
835
+ function easeBlendOut(state, off, x, y, z, dt) {
836
+ const px = x + off.x;
837
+ const py = y + off.y;
838
+ const pz = z + off.z;
839
+ const own = Math.hypot(px - ray.from.x, py - ray.from.y, pz - ray.from.z);
840
+ const was = state.drawnOut;
841
+ // Toward where the camera rests this frame (its place, which a start
842
+ // moved off a wall can put farther out than its distance), and let go
843
+ // within CAMERA_OUT_DONE of it, so a held blend always ends.
844
+ const rest = Math.hypot(x - ray.from.x, y - ray.from.y, z - ray.from.z);
845
+ const allowed = was + Math.max(0, rest - was) * eased(CAMERA_OUT_RATE, dt);
846
+ if (own <= allowed || rest - allowed <= CAMERA_OUT_DONE) return false;
847
+ blendDir.x = px - start.x;
848
+ blendDir.y = py - start.y;
849
+ blendDir.z = pz - start.z;
850
+ const length = Math.hypot(blendDir.x, blendDir.y, blendDir.z);
851
+ if (!(length > 0)) return false;
852
+ blendDir.x /= length;
853
+ blendDir.y /= length;
854
+ blendDir.z /= length;
855
+ const along = Math.min(length, alongRay(allowed, blendDir));
856
+ off.x = start.x + blendDir.x * along - x;
857
+ off.y = start.y + blendDir.y * along - y;
858
+ off.z = start.z + blendDir.z * along - z;
859
+ return true;
860
+ }
861
+
862
+ // Client-side, per-player shots only belong to the orbit camera. Neither
863
+ // its chosen angles nor its lens are changed; the deck places the shot clear
864
+ // of solids. Scratch is shared, while the drawn look travels with the actor.
865
+ const shotPose = { x: 0, y: 0, z: 0, yaw: 0, pitch: 0 };
866
+ function validOrbitShot(shot) {
867
+ const valid = shot && shot.look && Number.isFinite(shot.look.x) && Number.isFinite(shot.look.y)
868
+ && Number.isFinite(shot.look.z) && Number.isFinite(shot.distance) && shot.distance > 0
869
+ && Number.isFinite(shot.pitch) && Number.isFinite(shot.yaw);
870
+ if (!valid) return null;
871
+ const pitch = clamp(shot.pitch, -89, 89) * DEG;
872
+ const yaw = shot.yaw * DEG;
873
+ const flat = Math.cos(pitch);
874
+ shotPose.x = shot.look.x - flat * Math.sin(yaw) * shot.distance;
875
+ shotPose.y = shot.look.y + Math.sin(pitch) * shot.distance;
876
+ shotPose.z = shot.look.z + flat * Math.cos(yaw) * shot.distance;
877
+ shotPose.yaw = Math.atan2(flat * Math.sin(yaw), flat * Math.cos(yaw));
878
+ shotPose.pitch = pitch;
879
+ // Finite inputs can still overflow when added; treat that as absent too.
880
+ return Number.isFinite(shotPose.x) && Number.isFinite(shotPose.y) && Number.isFinite(shotPose.z) ? shot : null;
881
+ }
882
+ function ownsShotCamera(scene, drawnLook, cam, dt) {
883
+ return typeof drawnLook.placedAt === 'number' && Math.abs(scene.time - dt - drawnLook.placedAt) < PLACED_WITHIN
884
+ && drawnLook.atX === cam.position.x && drawnLook.atY === cam.position.y && drawnLook.atZ === cam.position.z
885
+ && drawnLook.qX === cam.quaternion.x && drawnLook.qY === cam.quaternion.y
886
+ && drawnLook.qZ === cam.quaternion.z && drawnLook.qW === cam.quaternion.w;
887
+ }
888
+ function recordShotCamera(scene, drawnLook, cam) {
889
+ drawnLook.placedAt = scene.time;
890
+ drawnLook.atX = cam.position.x;
891
+ drawnLook.atY = cam.position.y;
892
+ drawnLook.atZ = cam.position.z;
893
+ drawnLook.qX = cam.quaternion.x;
894
+ drawnLook.qY = cam.quaternion.y;
895
+ drawnLook.qZ = cam.quaternion.z;
896
+ drawnLook.qW = cam.quaternion.w;
897
+ }
898
+ function placeOrbitShot(scene, cam, rt, state, before, t, shot, dt) {
899
+ const drawnLook = (rt.orbitShot ??= { active: false, returning: false, x: 0, y: 0, z: 0 });
900
+ const continuing = drawnLook.active || drawnLook.returning;
901
+ if (!continuing || !ownsShotCamera(scene, drawnLook, cam, dt)) {
902
+ // The previous orbit look point gives the focus distance. Along the
903
+ // actual drawn direction, so even a camera another system placed has
904
+ // no rotation snap on entry. No temporary vectors on the frame path.
905
+ const at = cam.position;
906
+ const distance = (continuing
907
+ ? Math.hypot(at.x - shot.look.x, at.y - shot.look.y, at.z - shot.look.z)
908
+ : Math.hypot(at.x - (before?.x ?? t.x), at.y - ((state.heightTo ?? t.y) + LOOK_HEIGHT), at.z - (before?.z ?? t.z))) || shot.distance;
909
+ const q = cam.quaternion;
910
+ drawnLook.x = at.x - 2 * (q.x * q.z + q.w * q.y) * distance;
911
+ drawnLook.y = at.y + 2 * (q.w * q.x - q.y * q.z) * distance;
912
+ drawnLook.z = at.z + (2 * (q.x * q.x + q.y * q.y) - 1) * distance;
913
+ // The camera's right vector retains azimuth even when its forward
914
+ // vector is vertical. Seed it on entry or an ownership interruption.
915
+ drawnLook.yaw = Math.atan2(2 * (q.x * q.z - q.w * q.y), 1 - 2 * (q.y * q.y + q.z * q.z));
916
+ }
917
+ drawnLook.active = true;
918
+ drawnLook.returning = false;
919
+ const at = cam.position;
920
+ if (at.x === shotPose.x && at.y === shotPose.y && at.z === shotPose.z
921
+ && drawnLook.x === shot.look.x && drawnLook.y === shot.look.y && drawnLook.z === shot.look.z) {
922
+ drawnLook.yaw = shotPose.yaw;
923
+ cam.lookAt(drawnLook.x, drawnLook.y, drawnLook.z);
924
+ recordShotCamera(scene, drawnLook, cam);
925
+ return;
926
+ }
927
+ const k = eased(TAKEOVER_RATE, dt);
928
+ // Ease around the drawn focus, so opposite shots never cross through it.
929
+ const dx = at.x - drawnLook.x;
930
+ const dy = at.y - drawnLook.y;
931
+ const dz = at.z - drawnLook.z;
932
+ const flat = Math.hypot(dx, dz);
933
+ const distance = Math.hypot(flat, dy);
934
+ const yaw = flat < SHOT_YAW_EPS * distance ? drawnLook.yaw : Math.atan2(-dx, dz);
935
+ const pitch = Math.atan2(dy, flat);
936
+ const nextYaw = yaw + arc(shotPose.yaw - yaw) * k;
937
+ const nextPitch = clamp(pitch + (shotPose.pitch - pitch) * k, -SHOT_PITCH_LIMIT, SHOT_PITCH_LIMIT);
938
+ const nextDistance = distance + (shot.distance - distance) * k;
939
+ drawnLook.yaw = nextYaw;
940
+ drawnLook.x += (shot.look.x - drawnLook.x) * k;
941
+ drawnLook.y += (shot.look.y - drawnLook.y) * k;
942
+ drawnLook.z += (shot.look.z - drawnLook.z) * k;
943
+ if (Math.abs(arc(shotPose.yaw - nextYaw)) < SHOT_SETTLED && Math.abs(shotPose.pitch - nextPitch) < SHOT_SETTLED
944
+ && Math.abs(shot.distance - nextDistance) < SHOT_SETTLED
945
+ && Math.hypot(shot.look.x - drawnLook.x, shot.look.y - drawnLook.y, shot.look.z - drawnLook.z) < SHOT_SETTLED) {
946
+ drawnLook.x = shot.look.x;
947
+ drawnLook.y = shot.look.y;
948
+ drawnLook.z = shot.look.z;
949
+ drawnLook.yaw = shotPose.yaw;
950
+ at.set(shotPose.x, shotPose.y, shotPose.z);
951
+ } else {
952
+ const nextFlat = Math.cos(nextPitch);
953
+ at.set(drawnLook.x - nextFlat * Math.sin(nextYaw) * nextDistance,
954
+ drawnLook.y + Math.sin(nextPitch) * nextDistance,
955
+ drawnLook.z + nextFlat * Math.cos(nextYaw) * nextDistance);
956
+ }
957
+ cam.lookAt(drawnLook.x, drawnLook.y, drawnLook.z);
958
+ recordShotCamera(scene, drawnLook, cam);
452
959
  }
453
960
 
454
961
  // The orbit camera, placed at the end of the frame as the rigid one is
@@ -476,11 +983,32 @@ function placeOrbiting(scene, id, dt) {
476
983
  per.camLastAt = { x: t.x, z: t.z };
477
984
  const at = cam.position;
478
985
  const state = (rt.orbit ??= { off: { x: 0, y: 0, z: 0 } });
986
+ const shot = validOrbitShot(scene.orbitShot);
987
+ if (shot) {
988
+ placeOrbitShot(scene, cam, rt, state, before, t, shot, dt);
989
+ // `look` was consumed above and is deliberately dropped while held.
990
+ scene.orbitOwnModel = id;
991
+ return;
992
+ }
993
+ const drawnLook = rt.orbitShot;
994
+ const handBack = drawnLook?.active === true;
995
+ const keptShot = drawnLook && ownsShotCamera(scene, drawnLook, cam, dt);
996
+ if (handBack) {
997
+ drawnLook.active = false;
998
+ drawnLook.returning = keptShot;
999
+ drawnLook.offX = drawnLook.x - t.x;
1000
+ drawnLook.offY = drawnLook.y - t.y - LOOK_HEIGHT;
1001
+ drawnLook.offZ = drawnLook.z - t.z;
1002
+ }
1003
+ if (drawnLook && !keptShot) {
1004
+ drawnLook.returning = false;
1005
+ drawnLook.offX = drawnLook.offY = drawnLook.offZ = 0;
1006
+ }
479
1007
  // Placed on the frame before too: a frame this did not place on (the
480
1008
  // Player turned off, even by a collision callback after its update)
481
1009
  // breaks the chain.
482
1010
  const placed = typeof state.placedAt === 'number' && Math.abs(scene.time - dt - state.placedAt) < PLACED_WITHIN;
483
- const mine = placed && !jumped && state.x === at.x && state.y === at.y && state.z === at.z;
1011
+ const mine = !handBack && placed && !jumped && state.x === at.x && state.y === at.y && state.z === at.z;
484
1012
  if (mine) {
485
1013
  if (look && !look.locked) steerOrbit(per, chosen, look);
486
1014
  const k = eased(ORBIT_RATE, dt);
@@ -489,7 +1017,7 @@ function placeOrbiting(scene, id, dt) {
489
1017
  state.range += (chosen.range - state.range) * k;
490
1018
  state.height = settle(state.height, state.heightTo, t.y, dt);
491
1019
  } else {
492
- Object.assign(state, { yaw: per.camAngle, pitch: chosen.pitch, range: chosen.range, height: t.y, limit: Infinity });
1020
+ 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 });
493
1021
  }
494
1022
  state.heightTo = t.y;
495
1023
  const flat = Math.cos(state.pitch);
@@ -501,28 +1029,67 @@ function placeOrbiting(scene, id, dt) {
501
1029
  ray.from.x = t.x;
502
1030
  ray.from.y = state.height + LOOK_HEIGHT;
503
1031
  ray.from.z = t.z;
504
- limitReach(scene.physics3d, state, dt);
505
- const reach = Math.max(Math.min(state.range, state.limit), Math.min(CAMERA_NEAREST, state.range), 0);
506
- const x = ray.from.x + ray.dir.x * reach;
507
- const y = ray.from.y + ray.dir.y * reach;
508
- const z = ray.from.z + ray.dir.z * reach;
1032
+ const margin = lensMargin(scene, cam);
1033
+ limitReach(scene.physics3d, state, margin, dt);
1034
+ // Drawn at the nearer of its distance and the limit, out from the ball's
1035
+ // start (the look point, or a point moved off a surface it is pressed to).
1036
+ const reach = Math.max(Math.min(state.range, state.limit), 0);
1037
+ const x = start.x + ray.dir.x * reach;
1038
+ const y = start.y + ray.dir.y * reach;
1039
+ const z = start.z + ray.dir.z * reach;
1040
+ // How far from the look point it is placed, and the distance it was
1041
+ // placed for, for the next frame's ease.
1042
+ state.out = Math.hypot(x - ray.from.x, y - ray.from.y, z - ray.from.z);
1043
+ state.outRange = state.range;
509
1044
  const off = takenOver(state.off, at, x, y, z, mine, jumped, dt);
510
- if (Math.hypot(off.x, off.y, off.z) > BLEND_TESTED) holdBlend(scene.physics3d, off, x, y, z);
1045
+ state.blendHeld = Math.hypot(off.x, off.y, off.z) > BLEND_TESTED && blendHeldIn(scene.physics3d, state, off, x, y, z, margin, dt);
511
1046
  cam.position.set(x + off.x, y + off.y, z + off.z);
1047
+ // How far from the look point it is drawn, for a held blend's ease.
1048
+ state.drawnOut = Math.hypot(x + off.x - ray.from.x, y + off.y - ray.from.y, z + off.z - ray.from.z);
512
1049
  state.placedAt = scene.time;
513
1050
  state.x = at.x;
514
1051
  state.y = at.y;
515
1052
  state.z = at.z;
516
- cam.lookAt(t.x, t.y + LOOK_HEIGHT, t.z);
1053
+ if (drawnLook?.returning) {
1054
+ // Decay the hand-back offset, rather than chasing the moving player:
1055
+ // walking carries the look point immediately and cannot hold it open.
1056
+ const left = jumped ? 0 : Math.exp(-TAKEOVER_RATE * dt);
1057
+ drawnLook.offX *= left;
1058
+ drawnLook.offY *= left;
1059
+ drawnLook.offZ *= left;
1060
+ drawnLook.x = t.x + drawnLook.offX;
1061
+ drawnLook.y = t.y + LOOK_HEIGHT + drawnLook.offY;
1062
+ drawnLook.z = t.z + drawnLook.offZ;
1063
+ if (Math.hypot(drawnLook.offX, drawnLook.offY, drawnLook.offZ) < BLEND_TESTED) {
1064
+ drawnLook.offX = drawnLook.offY = drawnLook.offZ = 0;
1065
+ drawnLook.returning = false;
1066
+ } else {
1067
+ cam.lookAt(drawnLook.x, drawnLook.y, drawnLook.z);
1068
+ }
1069
+ }
1070
+ if (!drawnLook?.returning) {
1071
+ cam.lookAt(t.x, t.y + LOOK_HEIGHT, t.z);
1072
+ }
1073
+ if (drawnLook) recordShotCamera(scene, drawnLook, cam);
1074
+ // The actor the camera was placed for, for this frame's draw: its model is
1075
+ // left out of the frame if the final camera is inside it
1076
+ // (engine3d/ownmodel.js; the draw takes the name, a load drops it).
1077
+ scene.orbitOwnModel = id;
517
1078
  }
518
1079
 
519
- // The nearest Lookable the player is facing, within its range.
520
- function findLookText(scene, actor, t, facing) {
1080
+ // Count awake pickups in the same pass as the nearest Lookable, preserving
1081
+ // getActors order for equal-distance ties without two sorted/filtered lists.
1082
+ function hudContents(scene, actor, t, facing) {
521
1083
  const fx = Math.sin(facing);
522
1084
  const fz = Math.cos(facing);
523
1085
  let bestText = '';
524
1086
  let bestDist = Infinity;
525
- for (const other of scene.actorsWith('Lookable')) {
1087
+ let remaining = 0;
1088
+ for (const other of scene.getActors()) {
1089
+ const pickup = other.components?.Pickup;
1090
+ if (pickup && pickup.$enabled !== false) remaining += 1;
1091
+ const lookable = other.components?.Lookable;
1092
+ if (!lookable || lookable.$enabled === false) continue;
526
1093
  if (other.id === actor.id) continue;
527
1094
  const ot = other.components.Transform;
528
1095
  if (!ot) continue;
@@ -535,7 +1102,7 @@ function findLookText(scene, actor, t, facing) {
535
1102
  bestText = other.components.Lookable.text ?? '';
536
1103
  bestDist = dist;
537
1104
  }
538
- return bestText;
1105
+ return { remaining, look: bestText };
539
1106
  }
540
1107
 
541
1108
  export class Player {
@@ -572,9 +1139,13 @@ export class Player {
572
1139
  const shape = actor.components.Shape;
573
1140
  const dims = { radius: shape?.radius ?? 0.35, height: shape?.height ?? 1.4 };
574
1141
  // Under the camera key the player is held steady on screen: the hover
575
- // and the fall-faster pull are forces (hoverSteadily). Without it every
576
- // call below is the one made before the key had this meaning.
577
- const steady = scene.cameraFollowsRigidly === true;
1142
+ // and the fall-faster pull are forces (hoverSteadily). So they are under
1143
+ // the frame cap (`engine.maxFps`, `scene.maxFps` above 0), whose frames
1144
+ // are handed what they took, 1 to 3 physics steps' worth: there an
1145
+ // impulse per frame against gravity per step bobs the player with the
1146
+ // accumulator's carry (docs/engine-frame-cap.md). Without either key
1147
+ // every call below is the one made before the keys had this meaning.
1148
+ const steady = scene.cameraFollowsRigidly === true || scene.maxFps > 0;
578
1149
  const grounded = steady ? hoverSteadily(phys, actor, t, dims) : applyHover(phys, actor, t, dims, dt);
579
1150
  const drive = readDrive(scene.keys, scene.moveInput);
580
1151
  per.camAngle += drive.turn * this.props.turnSpeed * dt;
@@ -612,11 +1183,14 @@ export class Player {
612
1183
  }
613
1184
  }
614
1185
 
615
- if (scene.cameraFollowsRigidly !== true) updateCamera(scene, t, per, this.props, dt);
616
- const remaining = scene.actorsWith('Pickup').length;
1186
+ if (scene.cameraFollowsRigidly !== true) {
1187
+ if (scene.maxFps > 0) scene.followCamera = { id: actor.id, data: scene.data, dt, place: placeCapped };
1188
+ else updateCamera(scene, t, per, this.props, dt);
1189
+ }
1190
+ const { remaining, look } = hudContents(scene, actor, t, rt.facing);
617
1191
  const total = per.score + remaining;
618
1192
  const score =
619
1193
  total === 0 ? '' : remaining === 0 ? '◆ all shards found' : `◆ ${per.score}/${total}`;
620
- scene.hud = { score, look: findLookText(scene, actor, t, rt.facing) };
1194
+ scene.hud = { score, look };
621
1195
  }
622
1196
  }