castle-web-cli 0.4.233 → 0.4.235

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 (383) hide show
  1. package/dist/api.d.ts +11 -0
  2. package/dist/api.js +43 -0
  3. package/dist/bundle.d.ts +64 -0
  4. package/dist/bundle.js +558 -2
  5. package/dist/castle-host/host.d.ts +17 -2
  6. package/dist/castle-host/host.js +793 -36
  7. package/dist/castleJson.d.ts +20 -1
  8. package/dist/castleJson.js +44 -2
  9. package/dist/check.js +9 -2
  10. package/dist/chunkLoader.d.ts +3 -0
  11. package/dist/chunkLoader.js +111 -0
  12. package/dist/devParty.d.ts +26 -0
  13. package/dist/devParty.js +231 -0
  14. package/dist/devSaveStorage.js +4 -0
  15. package/dist/devSessionStorage.js +3 -1
  16. package/dist/devSocial.d.ts +24 -0
  17. package/dist/devSocial.js +70 -0
  18. package/dist/ide.d.ts +2 -0
  19. package/dist/ide.js +119 -15
  20. package/dist/index.js +8 -2
  21. package/dist/init.js +1 -1
  22. package/dist/save-deck.d.ts +20 -1
  23. package/dist/save-deck.js +141 -5
  24. package/dist/serve.js +29 -11
  25. package/dist/shell/assets/{index-BjOxR-lW.js → index-DulbYIJm.js} +97 -97
  26. package/dist/shell/index.html +1 -1
  27. package/dist/vitePlugins.d.ts +2 -1
  28. package/dist/vitePlugins.js +13 -0
  29. package/kits/base/castle.json +1 -1
  30. package/kits/base/sdk/README.md +266 -3
  31. package/kits/base/sdk/castle.d.ts +7 -3
  32. package/kits/base/sdk/castle.js +2 -0
  33. package/kits/base/sdk/commands.d.ts +162 -1
  34. package/kits/base/sdk/commands.js +3 -0
  35. package/kits/base/sdk/display.d.ts +3 -0
  36. package/kits/base/sdk/display.js +9 -3
  37. package/kits/base/sdk/hub.d.ts +33 -6
  38. package/kits/base/sdk/hub.js +68 -5
  39. package/kits/base/sdk/hubRejoin.d.ts +4 -0
  40. package/kits/base/sdk/hubRejoin.js +15 -0
  41. package/kits/base/sdk/multiplayer.d.ts +7 -1
  42. package/kits/base/sdk/multiplayer.js +147 -40
  43. package/kits/base/sdk/multiplayerProtocol.d.ts +2 -0
  44. package/kits/base/sdk/party.d.ts +23 -0
  45. package/kits/base/sdk/party.js +91 -0
  46. package/kits/base/sdk/reconnectBudget.d.ts +23 -0
  47. package/kits/base/sdk/reconnectBudget.js +96 -0
  48. package/kits/base/sdk/save.d.ts +38 -1
  49. package/kits/base/sdk/save.js +79 -6
  50. package/kits/base/sdk/server/hub.d.ts +31 -1
  51. package/kits/base/sdk/server/hub.js +50 -3
  52. package/kits/base/sdk/server/platformHandle.d.ts +13 -1
  53. package/kits/base/sdk/server/storage.d.ts +4 -0
  54. package/kits/base/sdk/server/storage.js +19 -3
  55. package/kits/base/sdk/server/wrapper.d.ts +7 -1
  56. package/kits/base/sdk/server/wrapper.js +10 -1
  57. package/kits/base/sdk/social.d.ts +9 -0
  58. package/kits/base/sdk/social.js +5 -0
  59. package/kits/hub-game/CLAUDE.md +123 -3
  60. package/kits/hub-game/README.md +63 -0
  61. package/kits/hub-game/castle.json +5 -5
  62. package/kits/hub-game/code/client/act.js +312 -0
  63. package/kits/hub-game/code/client/actionLayout.js +147 -0
  64. package/kits/hub-game/code/client/actionOverflow.js +556 -0
  65. package/kits/hub-game/code/client/arrivalCamera.js +50 -0
  66. package/kits/hub-game/code/client/askSlot.js +117 -0
  67. package/kits/hub-game/code/client/avatar.js +4 -2
  68. package/kits/hub-game/code/client/avatarShare.js +2 -0
  69. package/kits/hub-game/code/client/backVisibility.js +13 -0
  70. package/kits/hub-game/code/client/ballot.js +15 -10
  71. package/kits/hub-game/code/client/build.js +16 -0
  72. package/kits/hub-game/code/client/chat.js +41 -5
  73. package/kits/hub-game/code/client/chatModeration.js +5 -0
  74. package/kits/hub-game/code/client/chrome.js +1148 -258
  75. package/kits/hub-game/code/client/crowdNames.js +241 -0
  76. package/kits/hub-game/code/client/decor.js +10 -4
  77. package/kits/hub-game/code/client/defaultEnvironment.js +194 -0
  78. package/kits/hub-game/code/client/doorErrors.js +39 -0
  79. package/kits/hub-game/code/client/fall.js +18 -0
  80. package/kits/hub-game/code/client/farAvatars.js +233 -0
  81. package/kits/hub-game/code/client/firstJoin.js +9 -2
  82. package/kits/hub-game/code/client/fpsTelemetry.js +50 -0
  83. package/kits/hub-game/code/client/frameBatch.js +5 -0
  84. package/kits/hub-game/code/client/grab.js +31 -11
  85. package/kits/hub-game/code/client/hookLayer.js +87 -8
  86. package/kits/hub-game/code/client/hudCopy.js +51 -0
  87. package/kits/hub-game/code/client/hudRate.js +20 -0
  88. package/kits/hub-game/code/client/idle.js +14 -2
  89. package/kits/hub-game/code/client/invites.js +231 -0
  90. package/kits/hub-game/code/client/joinError.js +9 -0
  91. package/kits/hub-game/code/client/labelsNear.js +31 -2
  92. package/kits/hub-game/code/client/landscapeLayout.js +17 -0
  93. package/kits/hub-game/code/client/layoutCache.js +264 -0
  94. package/kits/hub-game/code/client/loadTelemetry.js +20 -0
  95. package/kits/hub-game/code/client/loadingCover.js +148 -0
  96. package/kits/hub-game/code/client/loadingEntry.js +8 -0
  97. package/kits/hub-game/code/client/menuRows.js +43 -0
  98. package/kits/hub-game/code/client/modelReady.js +7 -0
  99. package/kits/hub-game/code/client/padCueArrival.js +23 -0
  100. package/kits/hub-game/code/client/padCues.js +112 -0
  101. package/kits/hub-game/code/client/padOccupancy.js +88 -0
  102. package/kits/hub-game/code/client/padReadability.js +26 -0
  103. package/kits/hub-game/code/client/padRings.js +69 -0
  104. package/kits/hub-game/code/client/pushVisit.js +14 -0
  105. package/kits/hub-game/code/client/quality.js +205 -0
  106. package/kits/hub-game/code/client/qualityEntry.js +55 -0
  107. package/kits/hub-game/code/client/safeLayout.js +338 -0
  108. package/kits/hub-game/code/client/safeStyle.js +42 -0
  109. package/kits/hub-game/code/client/say.js +12 -3
  110. package/kits/hub-game/code/client/shot.js +64 -10
  111. package/kits/hub-game/code/client/shotFit.js +56 -0
  112. package/kits/hub-game/code/client/signIn.js +28 -0
  113. package/kits/hub-game/code/client/state.js +53 -0
  114. package/kits/hub-game/code/client/talk.js +209 -45
  115. package/kits/hub-game/code/client/tiers.js +68 -66
  116. package/kits/hub-game/code/client/together.js +7 -2
  117. package/kits/hub-game/code/client/weakestLookBake.js +92 -0
  118. package/kits/hub-game/code/client/weakestTier.js +295 -0
  119. package/kits/hub-game/code/client/worldLabels.js +241 -0
  120. package/kits/hub-game/code/client/yours.js +10 -9
  121. package/kits/hub-game/code/npcDisplayText.js +55 -0
  122. package/kits/hub-game/code/server/act.js +124 -0
  123. package/kits/hub-game/code/server/actions.js +6 -1
  124. package/kits/hub-game/code/server/actors.js +2 -1
  125. package/kits/hub-game/code/server/analytics.js +83 -0
  126. package/kits/hub-game/code/server/anonymousEntry.js +49 -0
  127. package/kits/hub-game/code/server/arrivalPose.js +36 -0
  128. package/kits/hub-game/code/server/companion.js +28 -3
  129. package/kits/hub-game/code/server/doorAnalytics.js +52 -0
  130. package/kits/hub-game/code/server/earned.js +22 -5
  131. package/kits/hub-game/code/server/frameBatch.js +183 -0
  132. package/kits/hub-game/code/server/friendsAmong.js +49 -9
  133. package/kits/hub-game/code/server/history.js +2 -0
  134. package/kits/hub-game/code/server/hub.js +1306 -95
  135. package/kits/hub-game/code/server/idle.js +30 -1
  136. package/kits/hub-game/code/server/index.js +26 -4
  137. package/kits/hub-game/code/server/invites.js +19 -0
  138. package/kits/hub-game/code/server/labels.js +9 -1
  139. package/kits/hub-game/code/server/loadAbandon.js +106 -0
  140. package/kits/hub-game/code/server/manifest.js +211 -3
  141. package/kits/hub-game/code/server/menu.js +31 -3
  142. package/kits/hub-game/code/server/npcs.js +226 -64
  143. package/kits/hub-game/code/server/observe.js +408 -0
  144. package/kits/hub-game/code/server/padOccupancy.js +85 -0
  145. package/kits/hub-game/code/server/players.js +9 -1
  146. package/kits/hub-game/code/server/resumePose.js +152 -0
  147. package/kits/hub-game/code/server/say.js +1 -1
  148. package/kits/hub-game/code/server/standing.js +4 -5
  149. package/kits/hub-game/code/server/storageLimit.js +187 -0
  150. package/kits/hub-game/code/server/vis.js +67 -5
  151. package/kits/hub-game/code/shared/act.js +35 -0
  152. package/kits/hub-game/code/shared/danceIdle.js +28 -0
  153. package/kits/hub-game/code/shared/loadStages.js +12 -0
  154. package/kits/hub-game/code/shared/quality.js +74 -0
  155. package/kits/hub-game/code/shared/say.js +2 -0
  156. package/kits/hub-game/code/shared/shot.js +35 -1
  157. package/kits/hub-game/code/systems/hub.js +970 -169
  158. package/kits/hub-game/docs/analytics.md +279 -0
  159. package/kits/hub-game/docs/contract.md +1259 -42
  160. package/kits/hub-game/docs/home-pieces.md +9 -2
  161. package/kits/hub-game/docs/observed-progress.md +252 -0
  162. package/kits/hub-game/main.jsx +2 -0
  163. package/kits/hub-game/package-lock.json +10 -3
  164. package/kits/hub-game/package.json +6 -3
  165. package/kits/hub-game/play/player.js +142 -0
  166. package/kits/hub-game/play/registry.js +47 -0
  167. package/kits/hub-game/play.jsx +37 -0
  168. package/kits/hub-game/scripts/check.mjs +39 -5
  169. package/kits/hub-game/scripts/companion-follower-wire.json +1 -1
  170. package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +11 -0
  171. package/kits/hub-game/scripts/fixtures/decor-keyless.json +5 -5
  172. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +3 -0
  173. package/kits/hub-game/scripts/fixtures/fake-dom.mjs +19 -3
  174. package/kits/hub-game/scripts/fixtures/interest-legacy.json +3 -3
  175. package/kits/hub-game/scripts/fixtures/vis-shared-wire.json +1 -1
  176. package/kits/hub-game/scripts/pose-storage-fixture.mjs +46 -0
  177. package/kits/hub-game/scripts/test-act-client.mjs +186 -0
  178. package/kits/hub-game/scripts/test-act.mjs +171 -0
  179. package/kits/hub-game/scripts/test-action-layout.mjs +80 -0
  180. package/kits/hub-game/scripts/test-action-observers.mjs +46 -0
  181. package/kits/hub-game/scripts/test-actions-client.mjs +367 -2
  182. package/kits/hub-game/scripts/test-actors.mjs +20 -7
  183. package/kits/hub-game/scripts/test-analytics.mjs +76 -0
  184. package/kits/hub-game/scripts/test-anonymous-entry.mjs +28 -0
  185. package/kits/hub-game/scripts/test-arrival-pose-server.mjs +196 -0
  186. package/kits/hub-game/scripts/test-arrival-pose.mjs +24 -0
  187. package/kits/hub-game/scripts/test-ask-slot.mjs +85 -0
  188. package/kits/hub-game/scripts/test-avatar-wire.mjs +49 -10
  189. package/kits/hub-game/scripts/test-avatar.mjs +44 -0
  190. package/kits/hub-game/scripts/test-back-visibility.mjs +82 -0
  191. package/kits/hub-game/scripts/test-ballot.mjs +11 -4
  192. package/kits/hub-game/scripts/test-ban-join.mjs +121 -13
  193. package/kits/hub-game/scripts/test-build.mjs +20 -2
  194. package/kits/hub-game/scripts/test-chat.mjs +206 -5
  195. package/kits/hub-game/scripts/test-companion-chat.mjs +20 -2
  196. package/kits/hub-game/scripts/test-control-layout-dom.mjs +120 -0
  197. package/kits/hub-game/scripts/test-crowd-names.mjs +205 -0
  198. package/kits/hub-game/scripts/test-decor-client.mjs +45 -4
  199. package/kits/hub-game/scripts/test-decor.mjs +7 -0
  200. package/kits/hub-game/scripts/test-default-environment-root.mjs +95 -0
  201. package/kits/hub-game/scripts/test-default-environment.mjs +267 -0
  202. package/kits/hub-game/scripts/test-door-analytics.mjs +58 -0
  203. package/kits/hub-game/scripts/test-door-jump.mjs +100 -0
  204. package/kits/hub-game/scripts/test-earned.mjs +33 -3
  205. package/kits/hub-game/scripts/test-far-avatars.mjs +340 -0
  206. package/kits/hub-game/scripts/test-fps-telemetry.mjs +112 -0
  207. package/kits/hub-game/scripts/test-frame-batch.mjs +252 -0
  208. package/kits/hub-game/scripts/test-fresh-friends.mjs +118 -0
  209. package/kits/hub-game/scripts/test-grab-orbit.mjs +47 -4
  210. package/kits/hub-game/scripts/test-high-only.mjs +170 -0
  211. package/kits/hub-game/scripts/test-hub-ops.mjs +321 -2
  212. package/kits/hub-game/scripts/test-hub-trip.mjs +879 -11
  213. package/kits/hub-game/scripts/test-hud-clear.mjs +162 -59
  214. package/kits/hub-game/scripts/test-hud-defects-dom.mjs +100 -0
  215. package/kits/hub-game/scripts/test-hud-rate.mjs +224 -0
  216. package/kits/hub-game/scripts/test-hud-safe-visibility-dom.mjs +83 -0
  217. package/kits/hub-game/scripts/test-idle.mjs +66 -0
  218. package/kits/hub-game/scripts/test-interest-cells.mjs +20 -0
  219. package/kits/hub-game/scripts/test-interest.mjs +15 -0
  220. package/kits/hub-game/scripts/test-invites-client.mjs +430 -0
  221. package/kits/hub-game/scripts/test-invites.mjs +109 -0
  222. package/kits/hub-game/scripts/test-labels.mjs +71 -3
  223. package/kits/hub-game/scripts/test-landscape-layout.mjs +194 -0
  224. package/kits/hub-game/scripts/test-list-scroll-dom.mjs +49 -0
  225. package/kits/hub-game/scripts/test-load-abandon.mjs +246 -0
  226. package/kits/hub-game/scripts/test-loading-cover.mjs +162 -0
  227. package/kits/hub-game/scripts/test-manifest.mjs +265 -0
  228. package/kits/hub-game/scripts/test-menu-client.mjs +105 -0
  229. package/kits/hub-game/scripts/test-menu.mjs +23 -0
  230. package/kits/hub-game/scripts/test-npcs.mjs +917 -10
  231. package/kits/hub-game/scripts/test-observed.mjs +745 -0
  232. package/kits/hub-game/scripts/test-pad-cues.mjs +304 -0
  233. package/kits/hub-game/scripts/test-pad-occupancy.mjs +177 -0
  234. package/kits/hub-game/scripts/test-picker.mjs +234 -7
  235. package/kits/hub-game/scripts/test-placement-cache.mjs +690 -0
  236. package/kits/hub-game/scripts/test-progress-reset.mjs +559 -0
  237. package/kits/hub-game/scripts/test-push-visit.mjs +26 -0
  238. package/kits/hub-game/scripts/test-quality.mjs +385 -0
  239. package/kits/hub-game/scripts/test-rehello.mjs +699 -5
  240. package/kits/hub-game/scripts/test-resume-action-order.mjs +598 -0
  241. package/kits/hub-game/scripts/test-resume-held.mjs +239 -0
  242. package/kits/hub-game/scripts/test-resume-pose.mjs +142 -0
  243. package/kits/hub-game/scripts/test-safe-events-dom.mjs +116 -0
  244. package/kits/hub-game/scripts/test-safe-layout.mjs +330 -0
  245. package/kits/hub-game/scripts/test-say.mjs +1 -1
  246. package/kits/hub-game/scripts/test-shot.mjs +145 -0
  247. package/kits/hub-game/scripts/test-signin-client.mjs +45 -0
  248. package/kits/hub-game/scripts/test-soundscape.mjs +22 -17
  249. package/kits/hub-game/scripts/test-standing.mjs +35 -2
  250. package/kits/hub-game/scripts/test-storage-limit.mjs +333 -0
  251. package/kits/hub-game/scripts/test-stuck.mjs +5 -4
  252. package/kits/hub-game/scripts/test-talk-overlay-dom.mjs +130 -0
  253. package/kits/hub-game/scripts/test-tiers-render.mjs +86 -13
  254. package/kits/hub-game/scripts/test-tiers.mjs +7 -8
  255. package/kits/hub-game/scripts/test-vis.mjs +433 -6
  256. package/kits/hub-game/scripts/test-weakest-tier.mjs +924 -0
  257. package/kits/hub-game/scripts/test-world-labels.mjs +367 -0
  258. package/kits/hub-game/scripts/test-yours-chrome.mjs +50 -6
  259. package/kits/hub-game/scripts/test-yours.mjs +39 -8
  260. package/kits/multiplayer-3d/castle.json +5 -5
  261. package/kits/multiplayer-3d/code/client/joinFailure.js +27 -0
  262. package/kits/multiplayer-3d/code/client/resumeGate.js +139 -0
  263. package/kits/multiplayer-3d/code/systems/multiplayer.js +369 -30
  264. package/kits/multiplayer-3d/package-lock.json +8 -1
  265. package/kits/multiplayer-3d/package.json +2 -1
  266. package/kits/multiplayer-3d/scripts/test-join-watchdog.mjs +436 -0
  267. package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +624 -0
  268. package/kits/physics-2d/CLAUDE.md +10 -1
  269. package/kits/physics-2d/castle.json +2 -2
  270. package/kits/physics-2d/engine/frozenActors.js +233 -0
  271. package/kits/physics-2d/engine/scene.js +87 -5
  272. package/kits/physics-2d/eslint.config.js +1 -1
  273. package/kits/physics-2d/play/behaviors/AnalogStick.js +198 -0
  274. package/kits/physics-2d/play/behaviors/Camera.js +40 -0
  275. package/kits/physics-2d/play/behaviors/Collider.js +122 -0
  276. package/kits/physics-2d/play/behaviors/Draggable.js +115 -0
  277. package/kits/physics-2d/play/behaviors/Goal.js +46 -0
  278. package/kits/physics-2d/play/behaviors/Joints.js +126 -0
  279. package/kits/physics-2d/play/behaviors/Layout.js +71 -0
  280. package/kits/physics-2d/play/behaviors/RigidBody.js +57 -0
  281. package/kits/physics-2d/play/behaviors/Slingshot.js +142 -0
  282. package/kits/physics-2d/play/behaviors/SoundPlayer.js +263 -0
  283. package/kits/physics-2d/play/behaviors/Sprite.js +406 -0
  284. package/kits/physics-2d/play/behaviors/Style.js +209 -0
  285. package/kits/physics-2d/play/behaviors/Text.js +85 -0
  286. package/kits/physics-2d/play/behaviors/Video.js +93 -0
  287. package/kits/physics-3d/CLAUDE.md +25 -1651
  288. package/kits/physics-3d/behaviors/Body.jsx +3 -0
  289. package/kits/physics-3d/behaviors/Model.jsx +3 -0
  290. package/kits/physics-3d/behaviors/Player.jsx +35 -18
  291. package/kits/physics-3d/behaviors/Shape.jsx +3 -0
  292. package/kits/physics-3d/behaviors/Solid.jsx +3 -0
  293. package/kits/physics-3d/behaviors/Transform.jsx +3 -0
  294. package/kits/physics-3d/castle.json +3 -3
  295. package/kits/physics-3d/docs/engine-camera.md +542 -0
  296. package/kits/physics-3d/docs/engine-frame-cap.md +136 -0
  297. package/kits/physics-3d/docs/engine-load.md +149 -0
  298. package/kits/physics-3d/docs/engine-look.md +114 -0
  299. package/kits/physics-3d/docs/engine-shadows.md +372 -0
  300. package/kits/physics-3d/docs/engine-skip-work.md +187 -0
  301. package/kits/physics-3d/docs/engine-sky.md +198 -0
  302. package/kits/physics-3d/docs/engine-static-actors.md +226 -0
  303. package/kits/physics-3d/docs/engine-view.md +37 -0
  304. package/kits/physics-3d/docs/pxmodel-format.md +1 -1
  305. package/kits/physics-3d/engine3d/PlayOnly3D.jsx +5 -1
  306. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +19 -333
  307. package/kits/physics-3d/engine3d/actornode.js +1 -0
  308. package/kits/physics-3d/engine3d/branches.js +3 -13
  309. package/kits/physics-3d/engine3d/cage.js +2 -7
  310. package/kits/physics-3d/engine3d/cageops.js +2 -17
  311. package/kits/physics-3d/engine3d/dataBehaviors.js +12 -0
  312. package/kits/physics-3d/engine3d/framecap.js +4 -1
  313. package/kits/physics-3d/engine3d/frozenphysics.js +140 -0
  314. package/kits/physics-3d/engine3d/frozenstatics.js +273 -0
  315. package/kits/physics-3d/engine3d/gait.js +8 -0
  316. package/kits/physics-3d/engine3d/initialModelFiles.js +18 -0
  317. package/kits/physics-3d/engine3d/look.js +7 -0
  318. package/kits/physics-3d/engine3d/modelFiles.js +3 -17
  319. package/kits/physics-3d/engine3d/modelMath.js +49 -0
  320. package/kits/physics-3d/engine3d/modelready.js +16 -0
  321. package/kits/physics-3d/engine3d/motion.js +3 -3
  322. package/kits/physics-3d/engine3d/nearshadows.js +77 -10
  323. package/kits/physics-3d/engine3d/orbitinput.js +59 -25
  324. package/kits/physics-3d/engine3d/partgeometry.js +1 -16
  325. package/kits/physics-3d/engine3d/paths.js +1 -9
  326. package/kits/physics-3d/engine3d/playTimings.js +50 -0
  327. package/kits/physics-3d/engine3d/playerRun.js +372 -0
  328. package/kits/physics-3d/engine3d/pxmodel.js +3 -3
  329. package/kits/physics-3d/engine3d/rapier.js +27 -0
  330. package/kits/physics-3d/engine3d/scatter.js +1 -11
  331. package/kits/physics-3d/engine3d/shadowfade.js +23 -15
  332. package/kits/physics-3d/engine3d/sky.js +1 -1
  333. package/kits/physics-3d/engine3d/squarefirst.js +177 -0
  334. package/kits/physics-3d/engine3d/stillshadows.js +399 -0
  335. package/kits/physics-3d/engine3d/sweep.js +1 -25
  336. package/kits/physics-3d/engine3d/world3d.js +468 -18
  337. package/kits/physics-3d/eslint.config.js +2 -1
  338. package/kits/physics-3d/main.jsx +6 -3
  339. package/kits/physics-3d/package-lock.json +7 -0
  340. package/kits/physics-3d/package.json +5 -1
  341. package/kits/physics-3d/play/behaviors/Body.js +31 -0
  342. package/kits/physics-3d/play/behaviors/Door.js +37 -0
  343. package/kits/physics-3d/play/behaviors/Lookable.js +16 -0
  344. package/kits/physics-3d/play/behaviors/Model.js +23 -0
  345. package/kits/physics-3d/play/behaviors/Pickup.js +46 -0
  346. package/kits/physics-3d/play/behaviors/Player.js +1204 -0
  347. package/kits/physics-3d/play/behaviors/Shape.js +47 -0
  348. package/kits/physics-3d/play/behaviors/Solid.js +16 -0
  349. package/kits/physics-3d/play/behaviors/Transform.js +29 -0
  350. package/kits/physics-3d/pnpm-lock.yaml +8 -0
  351. package/kits/physics-3d/scripts/bench-shadow-fade.mjs +37 -0
  352. package/kits/physics-3d/scripts/build-rapier-gz.mjs +56 -0
  353. package/kits/physics-3d/scripts/frozen-statics-fixture.mjs +141 -0
  354. package/kits/physics-3d/scripts/test-camera-follow.mjs +5 -1
  355. package/kits/physics-3d/scripts/test-camera-orbit.mjs +52 -4
  356. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +1 -1
  357. package/kits/physics-3d/scripts/test-empty-gait-hints.mjs +89 -0
  358. package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +6 -3
  359. package/kits/physics-3d/scripts/test-frame-cap.mjs +1 -1
  360. package/kits/physics-3d/scripts/test-frozen-nested.mjs +49 -0
  361. package/kits/physics-3d/scripts/test-frozen-statics-legacy-physics2d.mjs +123 -0
  362. package/kits/physics-3d/scripts/test-frozen-statics.mjs +434 -0
  363. package/kits/physics-3d/scripts/test-look-bake.mjs +1 -1
  364. package/kits/physics-3d/scripts/test-near-shadows.mjs +2 -2
  365. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +88 -7
  366. package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +40 -3
  367. package/kits/physics-3d/scripts/test-orbit-shot.mjs +75 -1
  368. package/kits/physics-3d/scripts/test-rapier-gz.mjs +106 -0
  369. package/kits/physics-3d/scripts/test-sky.mjs +1 -1
  370. package/kits/physics-3d/scripts/test-square-first.mjs +921 -0
  371. package/kits/physics-3d/scripts/test-static-actors.mjs +3 -1
  372. package/kits/physics-3d/scripts/test-static-physics.mjs +4 -1
  373. package/kits/physics-3d/scripts/test-static-scenery.mjs +5 -2
  374. package/kits/physics-3d/scripts/test-steady-hover.mjs +5 -2
  375. package/kits/physics-3d/scripts/test-still-shadows.mjs +477 -0
  376. package/kits/physics-3d/systems/physics3d.js +37 -4
  377. package/kits/real-time/castle.json +2 -2
  378. package/kits/real-time/code/client/connection.js +33 -10
  379. package/kits/real-time/code/client/gameHooks.js +2 -0
  380. package/kits/real-time/code/client/joinOverlay.js +9 -4
  381. package/kits/real-time/code/server/session.js +6 -4
  382. package/kits/real-time/package-lock.json +1 -1
  383. package/package.json +2 -2
@@ -0,0 +1,542 @@
1
+ # Scene key: engine.camera
2
+
3
+ The physics-3d kit's CLAUDE.md Quick reference points here. The key sits in
4
+ the `engine` object at a scene file's top level, beside `ground`.
5
+
6
+ - `"engine": { "camera": { "follow": "rigid" } }` at the scene file's top
7
+ level (the same `engine` object) asks the `Player` behavior for a follow
8
+ camera that moves with the player instead of easing after it. Without it
9
+ the camera eases its whole position toward its place behind the player, so
10
+ how far it trails a walking player depends on how long each frame is: on
11
+ frames of uneven length (a page missing every other vsync) the distance
12
+ changes every frame and the view judders, which reads as an up-and-down
13
+ shake walking forward, since the camera looks down. The terms:
14
+ > With the key absent, the camera is placed exactly as before: the same
15
+ > code, in the same place in the frame. With the key present, the camera's
16
+ > offset from the player (its angle and height) and the player's height are
17
+ > eased at the rate the old camera eases, with an easing that trails a
18
+ > steadily moving target by the same distance however the frames are cut;
19
+ > the player's ground position is not eased. So a steady walk leaves the
20
+ > player at one place on screen, a turn swings the camera round as before,
21
+ > and a jump lifts the player on screen while the camera follows smoothly.
22
+ > A teleport (more than 3 m in a frame, or the camera more than 20 m off)
23
+ > still snaps it, and it still looks at the player.
24
+
25
+ Where it is placed: behaviors run before physics, so the Player sees the
26
+ position the last frame drew. Under the key it asks for its camera instead
27
+ (`scene.followCamera`: its actor id and the scene data it asked in), every
28
+ frame, whether physics is ready or not, and the physics system places it
29
+ last in its `afterBehaviors`, after this frame's positions are written back
30
+ and the collision callbacks have run, on the position the frame is drawn
31
+ with; on a frame physics cannot step (rapier still loading, or the first
32
+ frame after a load) it is placed all the same. The player is looked up as
33
+ the scene has it then: one a callback despawned gets no camera, and a
34
+ request made before a load is not used after it (a load and a dispose drop
35
+ it). Systems registered after physics (the hub's) see the camera already
36
+ placed. The offset is read each frame from where the camera is, against
37
+ the point it followed the frame before, so a camera something else placed
38
+ (a hub trip's camera, a cutscene) is eased on from wherever it was put.
39
+ The play panel and a published deck play the scene through the same
40
+ runtime, so both follow the scene's key; the scene editor's own orbit
41
+ camera is not a follow camera and is not affected.
42
+
43
+ The key means "the player is held steady on screen", so it also changes
44
+ how the `Player` hovers. Without it the hover spring (and the fall-faster
45
+ pull) is an impulse, pushed once per drawn frame, while gravity pulls once
46
+ per fixed 1/60 physics step, and a frame takes none, one or two steps: on
47
+ a frame that is not exactly one step the player is kicked up or let drop,
48
+ a bob of 0.6 to 2 cm walking on a phone, which a camera that holds the
49
+ player still would show as the whole view bobbing. The terms:
50
+ > With the key absent, the Player makes the calls on `scene.physics3d` it
51
+ > made before, with the same arguments, in the same order. With the key
52
+ > present, the hover and the fall-faster pull are forces
53
+ > (`scene.physics3d.addForce`), which act once per physics step as gravity
54
+ > does: walking on flat ground the player's height does not move, whatever
55
+ > the frame lengths. The spring is the same one (160 and 18), resting
56
+ > 1.38 cm higher (`STEADY_REST`) so that the kit's player (gravity scale
57
+ > 2) stands where it does without the key, 0.7412 m, to within 0.01 mm; a
58
+ > jump reaches 2.348 m (2.347 on alternating frames) where without the key
59
+ > it reaches 2.347 to 2.354 m depending on the frames. A player with
60
+ > another gravity scale stands 0.69 cm per unit of scale off its keyless
61
+ > height. The walk push is an impulse either way (it leaves the height
62
+ > alone, and the rigid camera does not show its unevenness).
63
+
64
+ The rule for forces: **a force is for the frame it was asked in.** rapier
65
+ keeps a force on a body until it is reset, so nothing outside the physics
66
+ system puts one on a body. `addForce(actor, v)` writes down what was asked
67
+ (asking again in the frame adds; `resetForces(actor)` drops it: the
68
+ Player does that on the frame of a jump, or the frame's lift would add
69
+ 11 cm to it); the physics pass puts the forces on their bodies just before
70
+ the frame's fixed steps and takes them off straight after, in a `finally`
71
+ (`stepForced`, systems/physics3d.js), however many steps there were. So
72
+ between frames no body carries a force, and each of these leaves none: the
73
+ Player not running (turned off, physics not ready) asks for nothing; a
74
+ player despawned after asking has no body by the pass; a scene load or a
75
+ dispose (`reset`) drops what was asked, so a door trip from a keyed scene
76
+ to one without the key starts clean; the key going away means the next
77
+ frame asks for nothing; a frame that never reached physics, or a force
78
+ asked for after the pass (from a collision callback), is not used in a
79
+ later frame (requests carry the scene time they were asked at). Code that
80
+ places the player through its body (the hub's fall catch, the multiplayer
81
+ kit's placement and clamps: `setTranslation` and a zero velocity, after
82
+ physics) needs nothing new: there is no force to clear. A behavior that
83
+ wants a steady push asks every frame from `update`, and stops by not
84
+ asking. scripts/test-steady-hover.mjs holds all of it, on a stand-in
85
+ rapier and, where rapier is installed, on rapier itself.
86
+ - `"engine": { "camera": { "follow": "rigid", "control": "orbit" } }` (the
87
+ same `camera` object) asks the `Player` behavior for a third-person camera
88
+ the player controls: they turn it, tilt it and zoom it, walking is
89
+ relative to it, and the character turns to face the way it walks. Without
90
+ it the Player drives like a tank (A/D and a sideways drag steer, the
91
+ camera stays behind) and the camera's height and distance are the fixed
92
+ `camHeight` and `camDistance`. The terms:
93
+ > With `control` absent, everything is exactly as before: the same code,
94
+ > the same calls on `scene.physics3d` in the same order, the same camera,
95
+ > the same listeners on the canvas, for a scene with no camera key and for
96
+ > one with `"follow": "rigid"` alone. `control` means something only as
97
+ > exactly `"orbit"` beside exactly `"follow": "rigid"`; anything else, or
98
+ > `"orbit"` without the rigid follow, is as absent. The key is read when
99
+ > the scene loads (`scene.cameraControl`, `'orbit'` or `null`), as the
100
+ > other engine keys are. With the key present the Player hovers, jumps and
101
+ > falls as it does under `"follow": "rigid"` (forces), and the camera
102
+ > moves with the player as that one does: the player's ground position is
103
+ > not eased, its height is.
104
+
105
+ Controls under the key:
106
+ - Touch and pen: a drag that starts in the left half of the canvas is the
107
+ movement stick (the same stick, `scene.moveInput`: 56 px to full
108
+ deflection, analogue). A drag that starts in the right half turns and
109
+ tilts the camera, 0.006 rad per CSS pixel: dragging right swings the
110
+ view right, dragging up looks up (the camera goes lower). The left half
111
+ is the stick's: a finger that lands there is never part of a pinch, so
112
+ a thumb put down to walk while the other looks walks, and two thumbs
113
+ put down together walk and look. Two fingers that both landed in the
114
+ right half (the second while the first is still a tap or turning the
115
+ camera) are a pinch: fingers apart bring the camera nearer; while they
116
+ pinch neither turns the camera, a finger in the left half can still
117
+ take the stick, and the finger left when one lifts does nothing more
118
+ until it lifts too. A second drag in the left half while the stick is
119
+ held does nothing. A short tap that did not move still jumps, anywhere;
120
+ a finger that was part of a pinch, or left spent, never jumps.
121
+ - Mouse: a drag with any button turns and tilts, and is never the stick;
122
+ the wheel zooms, a tenth per notch; the context menu is kept off the
123
+ canvas. A left click that did not move jumps.
124
+ On a desktop a drag holds the pointer lock (Roblox's right-drag), so
125
+ the cursor hides and stays put while turning. A right press asks for
126
+ it at once. A left or middle drag asks once it passes the tap slop, or
127
+ when a second button is pressed while it is still a tap, so a click
128
+ never locks. While locked the turn comes from movementX/Y at the same
129
+ `LOOK_RAD_PER_PX`. The lock ends with the drag: the last button up, a
130
+ pointermove with no button down, the window's blur, the page hidden,
131
+ a scene load, or detach. Per the Pointer Lock spec the browser puts
132
+ the cursor back where the lock began. When the browser ends it
133
+ (Escape, or the host page taking focus), the drag ends with no tap. A
134
+ lock of ours that lands after the release, while the next press is
135
+ still a tap, or after a scene load, is let go of as soon as it is
136
+ known. A lock that lands takes the capture of every pointer down on
137
+ the canvas (the spec's implicit release), and no capture can be taken
138
+ while it is on. So every pointer down on the canvas gets its capture
139
+ back when a lock of ours ends, however it ends: under the key or
140
+ without it, mouse or touch, including a touch put down during the lock.
141
+ The captures are given back when our unlock's pointerlockchange
142
+ arrives, not when pointerLockElement clears. Chromium clears it inside
143
+ exitPointerLock and sends the event later. While a request of ours is
144
+ out, the lock is ours, or that event has not arrived, the document
145
+ listens (capture phase) for pointerup and pointercancel. A held
146
+ pointer lifted beyond the canvas in that window has its own event
147
+ handed to its own handler (Scene3DPlayer's pointerup handler, keyless
148
+ or not), so the stick stops and a tap still jumps, as origin/main's
149
+ capture would have done. A pointer whose lift was never seen and that
150
+ cannot be captured again is let go of as a pointercancel would be.
151
+ Scene3DPlayer's keyless handlers report their pointers to the orbit
152
+ input (`orbit?.pointer(event)`) in a runtime that has met the key; one
153
+ that never met it has no orbit input, and nothing changes. A lost pointerup never leaves a mouse pointer held: the next
154
+ press, a move with no button down, or a blur ends it. If
155
+ requestPointerLock is missing (iOS), throws, rejects (Chrome refuses a
156
+ re-lock about 1 s after Escape) or fires pointerlockerror, that drag
157
+ goes on unlocked on the pointer capture taken at the press, as before
158
+ the lock, and the next drag asks again. A drag request that returns a
159
+ promise is followed by the promise alone, and a pointerlockerror is
160
+ never taken for ours then. Old Safari returns no promise, so there an
161
+ error might be another element's, and our request stays watched for
162
+ 1 s after one. Touch and pen never lock. Listeners: blur and
163
+ visibilitychange while a mouse button is down under the key;
164
+ pointerlockchange while a drag has asked or our exit's event has not
165
+ come (a scene load between or not, so the captures can be given back);
166
+ the document's pointerup and pointercancel while a request is out, the
167
+ lock is ours, or that event has not come; and pointerlockchange and pointerlockerror while an
168
+ event-only request is out. A scene load with a request out leaves
169
+ only the document's pointerup and pointercancel listeners when the
170
+ request returns a promise, plus the request's own two when it does
171
+ not, until it is answered and any lock it brings has been let go of. Nothing at all without the key (engine3d/orbitinput.js
172
+ `makeMouseLock`;
173
+ scripts/test-camera-orbit.mjs `mouseLock`). castle.xyz's DeckPlayer
174
+ iframe is sandboxed with `allow-pointer-lock`.
175
+ On a desktop (`(hover: hover) and (pointer: fine)`, with pointer lock
176
+ supported), Shift or the small lock button at the bottom right toggles
177
+ shift lock. It starts off and is never saved. A repeated Shift keydown,
178
+ or one in an editable field, does not toggle; Shift still reaches
179
+ `scene.keys`. The button is made lazily beside the canvas under the
180
+ orbit key only, after game or navigation keyboard input. Pointer capability
181
+ alone does not show it; touch or pen hides it and ends an active lock.
182
+ It is hidden on every scene load until a keyed scene plays again, and
183
+ removed on detach. Clicking it gives focus back to the canvas.
184
+ The mode is on only once the pointer lock lands; a refused or missing
185
+ lock leaves it off. While on, every mouse move turns and tilts from
186
+ movementX/Y at `LOOK_RAD_PER_PX`, with no button needed. A quick left
187
+ click still jumps, presses never start a look-drag or take or release
188
+ the lock, and the wheel still zooms. Shift again, Escape or any browser
189
+ unlock, blur, the page hidden, every scene load, and detach end it,
190
+ with no look or stick left held. Held pointers get their captures back
191
+ through the same lock-end path as a drag. Touch and pen keep their
192
+ controls, and touch-only devices get no button. Nothing is made in a
193
+ runtime that never meets the orbit key. This changes only input: no
194
+ character facing or camera offset (scripts/test-orbit-shift-lock.mjs).
195
+ - Keys: W/S and up/down walk away from and toward the camera, A/D
196
+ strafe, left/right swing the camera, Space jumps.
197
+
198
+ What the Player's properties mean under it: `speed` and `jumpSpeed` are
199
+ what they were. `turnSpeed` is how fast left/right swing the camera,
200
+ rad/s; the character itself turns to face its walk at a fixed 12/s.
201
+ The character faces the way it walks; standing still it keeps its
202
+ facing. It starts facing away from the camera (PI - camAngle, as without
203
+ the key). Without the key its facing is always PI - camAngle, so code
204
+ that turns it sets camAngle; under the key the camera and the character
205
+ turn apart, and turning the character is asked for: `scene.faceRequest =
206
+ <radians>`, taken once by the Player's next update (a value that is not
207
+ a finite number is dropped) and dropped by a scene load. The hub asks
208
+ this way beside each of its camAngle writes (its arrival facing, a jump
209
+ to a door); any other deck that turns the player must do the same, since
210
+ a camAngle written without a request turns only the camera. The
211
+ player's own left/right and drags turn the camera only.
212
+ The camera is Roblox's default (Classic) third-person camera at our
213
+ scale. A Roblox character is 5 studs tall; the kit's avatar
214
+ (player.pxmodel on its 1.4 m capsule, the hub's) is 1.46 m from its soles
215
+ to the top of its cap, so one stud is 0.292 m (`STUD`), and every Roblox
216
+ distance below is that many studs:
217
+
218
+ | | Roblox | here |
219
+ | --- | --- | --- |
220
+ | look point | root part + 1.5 studs | Transform + 0.438 m (`LOOK_HEIGHT`): the Transform is the capsule's middle, which is the torso's middle as Roblox's root part is; 1.5 studs up is the neck |
221
+ | starting distance | 12.5 studs | `engine.camera.distance` in metres, clamped to 1.5..37.376 m; default 3.65 m (`ORBIT_START`), two and a half character heights |
222
+ | starting tilt | behind, slightly down | `engine.camera.pitch` in degrees down from horizontal (positive looks down), clamped to -80..80; default 15 degrees down (`ORBIT_PITCH_START`) |
223
+ | zoom | 0.5 to 128 studs | 1.5 m (`ORBIT_NEAREST`) to 37.4 m (`ORBIT_FARTHEST`, 128 studs): 0.5 studs is first person, and an avatar hides itself from a camera within about 1 m |
224
+ | tilt | 80 degrees either way | 80 degrees above to 80 below the horizontal (`ORBIT_PITCH_MOST`, `ORBIT_PITCH_LEAST`) |
225
+ | field of view | 70 degrees, vertical | 70 degrees, or the scene's `engine.camera.fov` (below) |
226
+ | occlusion (Popper) | snaps in front of what is in the way, eases back out | the same (Collision, below) |
227
+
228
+ `engine.camera.distance` and `engine.camera.pitch` are optional starting
229
+ values only, read only under the orbit key. Each absent, non-finite or
230
+ non-number value keeps its default exactly: 3.65 m or 15 degrees down.
231
+ They do not limit the player's zoom or tilt. `engine.camera.minPitch`
232
+ is an optional hard floor on the player's tilt, read only under the
233
+ orbit key: degrees down from horizontal (positive looks down), clamped
234
+ to -80..80. Absent, non-finite or non-number keeps the -80 degree floor
235
+ above. A value of 0 keeps the camera at or above the point it looks at;
236
+ a starting pitch below the floor is raised to it. Unlike `pitch`, this
237
+ floor limits the player's drags throughout play. `camDistance` and
238
+ `camHeight` do not move the orbit camera. A change to either of them,
239
+ either starting key or `minPitch` (a deck edit or a scene
240
+ with different values) reapplies both starting values; unchanged values
241
+ keep what the player chose throughout play. It looks at the player
242
+ 0.438 m above its Transform (the fixed cameras look 0.5 m above). Below
243
+ the horizontal the camera is lower than the point it looks at, looking
244
+ up, and the ground holds it above itself as a wall holds it in front
245
+ (Collision); a scene with `"ground": { "none": true }` has no drawn
246
+ ground to go under, and its floors are fixed solids that hold it alike.
247
+
248
+ Moment shots. Deck client code can set the player's runtime scene
249
+ (the `scene` passed to `Player`) to
250
+ `scene.orbitShot = { look: { x, y, z }, distance, pitch, yaw }`.
251
+ Distance is metres, greater than zero; pitch and yaw are degrees in the
252
+ orbit's sense (positive pitch puts the camera above the look point,
253
+ looking down). Pitches past 89 degrees in either direction are drawn at
254
+ 89 degrees in that direction; the blend also stays within those limits
255
+ to retain the view's azimuth. Its position is `look + distance * direction`,
256
+ where
257
+ `direction = { x: -cos(pitch)*sin(yaw), y: sin(pitch), z: cos(pitch)*cos(yaw) }`
258
+ with the angles converted to radians. Position and look point ease from
259
+ the drawn view at 10/s (`TAKEOVER_RATE`), then hold until changed or
260
+ cleared. The position eases in yaw (shortest arc), pitch and distance
261
+ around the drawn look point, so opposing shots swing round it. A settled
262
+ shot holds its exact pose. A changed shot eases from the current view;
263
+ an equal assignment continues it. After another system moves or turns
264
+ the camera or a frame without placement, a shot starts from its current
265
+ direction; an interrupted hand-back drops its look offset and looks at
266
+ the player.
267
+ The lens stays the orbit lens. The shot is drawn as given,
268
+ without collision: the deck author must place it clear of solids.
269
+ Clearing with `undefined` or `null`, or supplying an invalid shot
270
+ (missing look, non-finite numbers, distance <= 0), gives back the player's
271
+ chosen orbit through its usual takeover blend and collision handling;
272
+ the look point's offset from the player decays at 10/s, without a rotation
273
+ snap or trailing a walking player. Below 0.1 mm it returns to the exact
274
+ player look; a teleport clears the offset at once.
275
+ Look input is consumed and dropped during a shot. By default walking
276
+ keeps the player's camAngle basis. Opt into `engine.camera.walkFromShot: true`
277
+ to make keyboard and stick walking screen-relative while a valid shot is
278
+ held: use its drawn yaw during the blend, or its target yaw before the
279
+ first placement. This does not change camAngle; absent/false or no valid
280
+ shot keeps the existing walking behavior.
281
+ The player's camAngle, zoom and tilt are kept. Shot state
282
+ lives on actor.runtime, per player; without the orbit key it is never
283
+ read, and a scene that never sets it keeps its camera and movement.
284
+ Checked by scripts/test-orbit-shot.mjs, also run by test-camera-orbit.mjs.
285
+
286
+ The lens. The world camera is 50 degrees tall (`makeWorld3D`), and no
287
+ scene key changes it without the orbit key. Under the key it is
288
+ `engine.camera.fov` degrees (the same `camera` object: a number from 10
289
+ to 120; anything else, or none, is 70, Roblox's), read from the scene the
290
+ runtime loaded, set on the world camera with `updateProjectionMatrix` by
291
+ `renderWorld` on each keyed frame (engine3d/orbitlens.js). The lens the
292
+ camera had when the key first met it is kept (`world.orbitLens`) and
293
+ given back exactly, projection and all, when the keyed scene goes, before
294
+ any code of what follows runs: at every scene load (the physics system's
295
+ `reset`, which `load` runs before the new scene's data is in), on an
296
+ editor's frame and on `disposeWorld`. So a keyless scene after a keyed
297
+ one (a door to a keyless deck in the same world) starts from the lens the
298
+ camera had, and whatever field of view its own code sets stands, 70
299
+ included: no keyless frame looks at the camera. A keyed scene after a
300
+ keyed one takes the lens again on its first frame. A world that never
301
+ plays the key never touches the camera. The editors have their own worlds
302
+ and cameras. (Instanced copies are culled before `renderWorld`, with the
303
+ lens of the frame before: on a keyed scene's first frame they are culled
304
+ with 50 degrees.)
305
+
306
+ Limits: the tilt stays between 80 degrees below and 80 above the
307
+ horizontal and the distance between 1.5 and 37.376 m. What is asked is
308
+ eased in at 20/s.
309
+
310
+ Collision (Roblox's Popper, with a ball): each frame a ball of the
311
+ margin's radius (below) is swept from the point the camera is placed
312
+ from (the player, with its height eased as the camera eases it, 0.438 m
313
+ up) toward where the camera wants to be, as far as its distance, against
314
+ fixed bodies' solid colliders only (`scene.physics3d.castBallFixed(origin,
315
+ dir, maxToi, radius)`, rapier's `castShape` with a `Ball` and the filter
316
+ of `castRayFixed(origin, dir, maxToi)`: sensors and dynamic and kinematic
317
+ bodies are passed through, so other players and thrown things do not move
318
+ the camera). Where it first touches something (its time of impact) is a
319
+ limit on how far out along that line the camera may be. A ball that far
320
+ out is the margin off whatever stopped it and off everything it passed,
321
+ square to the surface, however the line meets it: a wall at a grazing
322
+ angle, a box's edge or corner, the ground seen along at a low angle, a
323
+ second wall in a corner. The margin is 0.25 m, or, for a wider lens, the
324
+ distance from the camera to the near plane's corners, near * sqrt(1 +
325
+ tan^2(fov/2) + (aspect * tan(fov/2))^2), plus 0.05 m, whichever is more
326
+ (`lensMargin`, from the scene's lens and the camera's near and aspect):
327
+ 0.25 m at 70 degrees on 20:9 (corners 0.198 m off), 0.484 m at 120
328
+ degrees on 20:9, 0.265 m at 120 on 9:20. So the whole near plane stays in
329
+ front of every surface at every lens from 10 to 120 degrees, any aspect,
330
+ every tilt and zoom. A nearer limit is taken at once; a farther one, or
331
+ none, is eased out to at 6/s, never past what this frame's ball touched,
332
+ and let go once the camera is back at its distance. The ease is measured
333
+ from the look point, from how far from it the camera was drawn last
334
+ frame, and turned into a distance along this frame's line from this
335
+ frame's start (`alongRay`): the start moves as the player nears or leaves
336
+ a wall, so last frame's limit along its own line is not where the camera
337
+ was (review 7: a wall 0.5 m off removed let the camera out 1.161 m in a
338
+ frame where easing at 6/s allows 1.139). It eases whatever drew the
339
+ camera short of its distance, a start moved off a wall as well as a ball
340
+ that held it (review 8: a box beside the look point removed let the camera
341
+ out 0.062 m where 0.006 m is allowed); only the player's zoom moves it at
342
+ the zoom's own pace (a zoom in past where it is held takes it in at once).
343
+ The ball is swept only as far as the camera will be drawn this frame, so
344
+ the place drawn is the place whose end the sweep checks. The camera is drawn at the nearer of its eased distance and the
345
+ limit, so zooming in while held in front of a wall brings it no nearer
346
+ until the distance asked is nearer than the wall, the view is never
347
+ inside a wall and never pops outward, and an easing camera never passes
348
+ something the ball touches (review 5: the axis-ray push and line pull-in
349
+ of reviews 3 and 4 left a camera 8 mm off a box at a grazing angle, and a
350
+ pull-in made for one frame alone let the eased limit run on, so the
351
+ camera jumped 3.985 m out in a frame when it stopped).
352
+
353
+ Rapier's answer for a swept ball is off by an amount that changes from
354
+ place to place (short by centimetres against the ground and tens of
355
+ centimetres along a wall met at a grazing angle; past the surface by up
356
+ to 2 cm, or missing it, when the ball starts within a few centimetres of
357
+ one; in a corner it can name the second solid instead of the first), so
358
+ `castBallFixed` puts the ball where it touches the plane that touches the
359
+ solid where it was met (exact on a face; a convex solid is all behind it
360
+ at an edge or a corner) and checks that place with an overlap query, the
361
+ ball 0.05 mm smaller; another solid in the way there is swept against
362
+ alone and the ball put where it touches that one, three times at most.
363
+ Rapier can also miss a solid outright (review 8: a box the ball passes
364
+ through, at one radius and not a millimetre more), so its answer is only
365
+ where to look: with no hit the ball's end (the place the camera will be
366
+ drawn) is checked all the same, a ray along the line keeps the line of
367
+ sight, and a place still not clear is found by halving between the start
368
+ (clear) and it with overlap queries, to 1 mm in 16 halvings at most.
369
+ `castBallFixed` is three rapier queries as a rule (sweep, ray, overlap)
370
+ and 25 at most. Rapier does not answer a ball that
371
+ starts touching something either, so the ball starts clear: every fixed
372
+ surface within the margin and 0.05 m of the start
373
+ (`scene.physics3d.nearFixed(point, within)`, each solid's nearest point and
374
+ normal) gives a plane touching its solid there (a convex solid all behind
375
+ it), and the start is the look point moved the least way that puts it
376
+ that far in front of every plane found so far, all together (the nearest
377
+ point of the half-spaces' intersection), then looked around again, eight
378
+ times at most. Together, a corner's walls do not undo each other's moves
379
+ (review 6: one wall at a time, a 60 degree corner left the camera 8.66 mm
380
+ off a wall with the near plane through it). The move grows from nothing as
381
+ the player comes nearer, so the camera does not jump. Where no place near
382
+ the look point is that far off every plane (a gap narrower than twice the
383
+ margin) the place that falls least short is taken and the ball made that
384
+ much smaller (in a gap 0.7 m wide, its middle, the camera 0.3 m off both
385
+ walls), no smaller than 0.02 m. There the lens cuts into the walls: the
386
+ camera point stays out of them, but no place keeps the near plane out
387
+ (at 120 degrees on 20:9 its corners are 0.434 m from the camera), so the
388
+ view shows the inside of a wall at its edges. This is accepted, as
389
+ Roblox's camera clips there too; the near plane is not shrunk. Only a look point inside a solid falls back to the ray the
390
+ camera had before the ball (`onRay`, with `castRayFixedNormal`, which is
391
+ `castRayFixed` with the surface's normal): a margin short of the hit, no
392
+ nearer the look point than 0.6 m, never past a real surface (then 0.01 m
393
+ short of it). `castRayFixed` itself is what it was: `{ distance, actorId }`.
394
+ While a takeover blend lasts (below) the point actually drawn, its place
395
+ plus what is left of the blend, is swept toward the same way: pulled in
396
+ along its own line to where the ball stopped, and the pull is kept in the
397
+ blend, so the next frame eases on from there. Once a wall has held a
398
+ blend in, it is let out at the collision pace for the rest of that blend:
399
+ no farther from the look point than easing at 6/s from where it was drawn
400
+ toward where the camera rests this frame (review 9: a wall removed under a
401
+ held blend let its 10/s carry the camera 0.246 m out in a frame where
402
+ 0.179 m is allowed), and let go within 0.1 mm of it. Where it rests, not
403
+ its distance: a start moved off a wall can put the camera farther out
404
+ than its distance, and easing toward the distance held such a blend open
405
+ for good (review 10: 0.093 m short after 20 s, a sweep more every frame).
406
+ A blend no wall has held keeps its own pace. Tests
407
+ (scripts/test-camera-orbit.mjs): `grounded` on a stand-in plane and on
408
+ rapier's own ground, `wideLens` on a stand-in wall, `grazing` on rapier
409
+ (the review 3 case at 120 degrees, 20:9, level, yaw -3, farthest zoom; a
410
+ sweep near grazing on 20:9 and 9:20 at 70 and 120 degrees, a player 0.8 m
411
+ from the wall and against it; a corner of two walls over the ground;
412
+ review 4's post, 240 settled frames whose line to the player meets
413
+ nothing and that do not move), `popClear` and `popSteady` (review 5 on
414
+ rapier: two boxes beside the line and a blocker removed; every frame
415
+ after, the camera is the margin off each box and the ground, measured on
416
+ the boxes, and moves out no faster than easing at 6/s allows), `corners`
417
+ (review 6 on rapier: the player pressed into corners of 30 to 150
418
+ degrees, two square walls under a ceiling and a 60 degree corner under
419
+ one, the camera turned every way: every frame the margin off every solid,
420
+ less 0.1 mm, and no near-plane corner inside one), `narrowGapStable`
421
+ (walls 0.7 m apart: only that the camera point is never inside a wall,
422
+ nothing is NaN and a settled camera stays put; the lens does cut the
423
+ walls there) and `releaseEase` (review 7: walls 0.36 to 0.6 m off at four
424
+ angles, removed; no frame moves the camera out from the look point
425
+ faster than easing at 6/s allows).
426
+ Also `releaseBeside` (review 8: a box beside the look point removed, eased
427
+ out at 6/s), `randomBoxes` (review 8: 120 seeded cases of one or two
428
+ boxes turned any way, mostly in the camera's way, 70 and 120 degrees on
429
+ 16:9 and 20:9; every frame the camera the margin off each box less 1 mm
430
+ and no point of a 21 x 21 near-plane grid inside one; the review's case
431
+ is the first), `ballMisses` (rapier's sweep made to miss: the ball
432
+ still stops its radius off the wall) and `blendRelease` (review 9: blends
433
+ handed back from three places, a wall at two distances removed or kept,
434
+ no wall, and (review 10) a wall and a corner 0.4 m off at 70 and 120
435
+ degrees: eased out at 6/s once released, every blend ends and is no
436
+ longer held, one sweep a frame after, the camera stays, and with no wall
437
+ it is about there in 0.3 s). Queries a frame: one `nearFixed` in
438
+ the open, two by a wall or in a corner (eight at most), and one sweep, one
439
+ more while a takeover blend lasts; a sweep is three rapier queries as a
440
+ rule and 25 at most. As a rule 4 in the open and 5 by a wall; the worst
441
+ case is 8 + 2 * 25 = 58 (a blend, a slanted corner, and rapier missing
442
+ solids in both sweeps); none on a
443
+ frame physics has no world. Popped in near the player the camera
444
+ is within an avatar's own hiding distance, as Roblox's goes through its
445
+ character when pressed close, and the model is hidden (below).
446
+ A frame whose final camera (after anything else placed it) is within
447
+ 1 m of the player's own model (in world space, the segment from its
448
+ node's origin 0.8 m up, to the top of its head; once hidden, until 1.2 m) is drawn without that model, so
449
+ the view is not the inside of the avatar (engine3d/ownmodel.js). The
450
+ Player names its actor for the frame's draw (`scene.orbitOwnModel`, set
451
+ by each placement, taken by the draw, dropped by `reset`), and the play
452
+ loop sets that node's `visible` to false for the one render (only a node
453
+ that was shown), inside try/finally, and back to true after it if it is
454
+ still false; nothing else is put on the node, so a deck's own hide, a
455
+ rebuilt node and a Player turned off or removed need nothing. Positions
456
+ are measured as WebGLRenderer.render will draw them (`world.scene`
457
+ updated when its `matrixWorldAutoUpdate` is on, cached when off; a
458
+ parentless camera by its own flag), writing no matrix; a node not under
459
+ `world.scene` is not hidden. A `false` a deck writes from inside the
460
+ render of a hidden frame is shown again after it. Accepted: anything
461
+ that copies the node from inside that render (clone, copy, toJSON, its
462
+ own or a parent's) copies `visible: false`, as for any node a deck hides
463
+ for a frame; three.js treats `visible` as plain state. Also accepted: the
464
+ decision is made before the render, so a camera a deck moves from
465
+ `scene.onBeforeRender` (which three.js calls after the matrices, before
466
+ the render list) is judged where it was before that callback; under the
467
+ key the Player places the camera, and catching that callback would mean
468
+ putting something on the scene. Only the
469
+ local player is hidden; nothing is sent. While hidden it casts no
470
+ shadow; a model drawn as shared instances (`instanceModels`) is not
471
+ hidden. Without the key the field is never set and the loop calls
472
+ `renderWorld` as before.
473
+
474
+ `scene.three.ownModelWith` is a `Set<Object3D>` for extras that should hide
475
+ with the own model, such as multiplayer-3d's own name-tag sprite. Add an
476
+ object while it belongs to the player and delete it when disposed or
477
+ replaced. The set is read only in a render that actually hides the model;
478
+ keyless frames never read it. Only shown, writable objects under
479
+ `world.scene` are hidden, with the same try/finally visibility contract as
480
+ the model; anything other than a Set there is ignored. Detaching or unregistering one during the render still restores
481
+ it if its visibility is still false; an already hidden object is left alone.
482
+
483
+ There is no return-behind (no swinging the camera back behind a walking
484
+ player when it is left alone): walking forward already keeps the camera
485
+ behind, and chasing a strafe would turn a straight walk into a circle.
486
+
487
+ Where the state is. The yaw is `scene.persistent.camAngle`, with the
488
+ meaning it always had (the camera sits at player + (-d sin, h, d cos) of
489
+ it), so code that reads or sets it (the hub's arrival facing) works as
490
+ before; a yaw set a full turn away is reached the short way round. The
491
+ tilt and distance the player chose are client-only: they are on the
492
+ runtime (`scene.cameraOrbit`), which a scene load does not replace, so
493
+ they carry from scene to scene (a Player with other
494
+ `camDistance`/`camHeight` starts from its own), and are never on
495
+ `scene.persistent`, which the multiplayer kit sends. What the camera is
496
+ doing between frames is on the actor's `runtime`, which a scene load
497
+ rebuilds. `scene.lookInput` (engine3d/orbitinput.js) holds what the
498
+ pointers asked for until the Player takes it, once a frame; it is made
499
+ the first time a pointer goes down under the key or a Player runs under
500
+ it (`scene.orbitInput()`), so a runtime that never meets the key has
501
+ none.
502
+
503
+ When something else has the camera. A teleport (more than 3 m in a
504
+ frame) snaps it, and so does a camera more than 20 m from its place. The
505
+ camera is the player's to steer on a frame only when the Player also
506
+ placed it on the frame before (so a Player turned off, even for a frame
507
+ and even by a collision callback after its update, does not come back to
508
+ a queued drag), the camera is where the Player left it, and the look
509
+ input is not locked. `scene.lookInput.lock()` makes the next take empty
510
+ and drops what was asked; the hub calls it each frame of a door trip
511
+ under the key (beside its `lockInput`), so a drag made during a
512
+ trip neither moves the trip's camera nor turns the view when it ends. On
513
+ any frame the camera is not where the Player left it (a hub trip writes
514
+ it every frame; the first frame of a scene; a Player turned off and on)
515
+ the Player starts again from the chosen tilt and distance and eases on
516
+ from where the camera was put (a twentieth of the way left after 0.3 s).
517
+
518
+ Loads. A scene without the key, loaded after one with it, runs the code
519
+ it always ran from its first frame: the latch is per load, and the
520
+ Player's and the input's branches each read it once. On every scene
521
+ load and on dispose the physics system's `reset` resets the orbit input
522
+ (`scene.lookInput.reset()`, only when it is the one orbitinput.js made:
523
+ `isOrbitLook`): every pointer it holds is let go of (the stick released
524
+ if one of them held it, no tap), what was asked of the camera is
525
+ dropped, and the wheel and context-menu listeners are taken off; a keyed
526
+ scene's Player puts the listeners back on its first frame. A
527
+ `faceRequest` not yet taken is dropped on every load, whether or not the
528
+ orbit input was ever made. A tap already taken as a jump and not yet
529
+ used carries across a load with or without the key, as it always has. A
530
+ runtime that never met the key has no orbit input.
531
+ So a finger held across any load into or out of a keyed scene, or
532
+ between two keyed scenes, does nothing more until it lifts: the old
533
+ handlers do not know it either. A finger the old handlers hold across a
534
+ load into a keyed scene keeps their stick until it lifts or a pointer
535
+ goes down under the key, which lets go of everything they hold; only
536
+ one of the two ever writes the stick. scripts/test-camera-orbit.mjs
537
+ holds all of it, with the Player as it was before the key
538
+ (scripts/Player.before-orbit.mjs) and Scene3DPlayer's `attachInput` as
539
+ it was (scripts/Scene3DPlayer.before-orbit.jsx) as the references for
540
+ the scenes without it, and the loads, the lock and a Player turned off
541
+ and on run through physics-2d's SceneRuntime and Scene3DPlayer's own
542
+ `attachInput`.