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
@@ -35,7 +35,7 @@ bottom }`; any ref can pick a frame of a multi-frame sprite with
35
35
  `mass`, `castRay(origin, dir, maxToi, excludeActor)` (rays skip sensors).
36
36
  `addForce(actor, {x,y,z})` pushes through this frame's physics steps only
37
37
  (ask every frame from `update` for a steady push; `resetForces(actor)`
38
- drops what the frame asked): the camera section below has the rule.
38
+ drops what the frame asked): docs/engine-camera.md has the rule.
39
39
  Fixed/kinematic actors ARE moved by writing their Transform.
40
40
  - The scene has the lighting rig built in (hemisphere + ambient + one
41
41
  shadow-casting sun, ground plane at y=0); meshes cast and receive shadows
@@ -61,1656 +61,30 @@ bottom }`; any ref can pick a frame of a multi-frame sprite with
61
61
  or stood on: whatever is not on an actor falls (pits, lava, sky islands).
62
62
  `Shape.artRepeat: [u, v]` tiles a texture across a
63
63
  face so long walls don't stretch.
64
- - `"engine": { "skipUnchangedActors": true }` at the scene file's top level,
65
- beside `ground`, asks the engine not to redo, every frame, work whose answer
66
- cannot have changed. The terms:
67
- > With the key absent, a scene runs the engine exactly as before. With the key
68
- > present, each frame equals what the engine would have produced without it
69
- > PROVIDED the scene's components are plain stored data (no accessors, Proxies,
70
- > toJSON, custom iterators) and three.js objects under actors are changed only
71
- > through position/rotation/quaternion/scale/visible/parenting. A scene that does
72
- > not meet that is unsupported under the key and must not set it.
73
-
74
- It is read when the scene loads, so it follows a scene switch, and a mounted
75
- pack's scene decides for itself. What is skipped for an actor nothing has
76
- touched: building the signatures that decide whether its mesh and its
77
- physics body need rebuilding, recomputing its node's matrices, and sorting
78
- the actor list. Behaviors run exactly as without the key. Each skipped piece
79
- is skipped only after reading its inputs and finding them as they were, so
80
- nothing has to be marked dirty: an actor still follows a change on the very
81
- next frame -- a component's stored field written in place, a component
82
- added, removed or replaced, a spawn or despawn, physics, the editor, the
83
- network, its node posed from `scene.three`. Opt in when a scene is several
84
- hundred actors that mostly stand still and frame time on a slow phone is
85
- script, not drawing; a small scene gains nothing.
86
- How it stays right when deck code runs in the middle of the engine's own
87
- work (`engine3d/world3d.js` has the rule and the code):
88
- > Fast-path state (snapshots, pass marks, cached signatures) is trusted only
89
- > across a span in which no code outside the engine has run. A pass in which
90
- > the engine calls out (any callback), is re-entered, or sees the scene
91
- > change, finishes exactly as main would and leaves no fast-path state
92
- > behind.
93
-
94
- The engine moves a counter before it does anything, inside a pass over the
95
- actors, that can run code that is not its own; it does not work out
96
- afterwards whether something ran. The places, all of them:
97
- `scene.three.scene.userData.groundHeight`, called while a walking model is
98
- animated; and three.js listeners (`added`, `removed`, `childadded`,
99
- `childremoved`, `dispose`) on the scene, a node, a geometry or a material,
100
- told when a node is built, rebuilt or released, when the scene changes, when
101
- the ground is dressed anew, and when an instanced mesh is replaced; and
102
- `syncActors` called again from inside any of those. From that point the
103
- pass does each actor the old way and writes nothing down, and when it ends,
104
- or if it throws, everything written down before is dropped. So:
105
- - a frame in which any actor's mesh is built, rebuilt or released costs what
106
- it costs without the key, and the frame after it reads every actor once
107
- more before skipping resumes;
108
- - a scene with a `groundHeight` callback, or with `instanceModels` on, runs
109
- every pass the old way and keeps only the matrix saving;
110
- - the physics pass calls nothing outside the engine until its collision
111
- callbacks, which come last;
112
- - a component nested more than 32 levels deep is compared the old way every
113
- frame.
114
-
115
- What is written down lives in the world's own maps (`world.snapshots`,
116
- `world.modelSigs`) and in the physics system's (`remembered`), never on a
117
- node entry or a body entry, and is dropped by replacing or clearing those.
118
- The one thing on a node, an ActorNode's `computedFrom`, is numbers only and
119
- refers to no object.
120
- A world being disposed never skips: `disposeWorld` drops what was written
121
- down before it releases the nodes and again after their `dispose` listeners
122
- have run, so a listener that syncs the world again leaves nothing.
123
- - Within the terms, these are followed: any stored field of a Shape, Model,
124
- Body or Transform changed, added, removed or reordered, at any depth; art
125
- loading or being replaced; a model file, or a model it references, edited;
126
- a node's, or any object under it's, position, rotation (angles or order),
127
- quaternion, scale or visibility set; children added, removed, reordered,
128
- or moved to another parent and back; a body's type changed through
129
- `scene.physics3d.bodyOf`.
130
- - Outside the terms the result is not promised. The engine does notice some
131
- of it and then does the old work for that actor, as protection, not as a
132
- guarantee to build on: a component with an accessor, a `toJSON` or a class
133
- of its own found when it is first read; an object under a node with
134
- `matrixAutoUpdate` off or an `updateMatrixWorld` of its own (a camera, a
135
- skinned mesh); a world matrix written by hand; a transform changed, used
136
- and put back between frames.
137
- - It does not notice, among others: a `Proxy` in place of a component, of
138
- `actor.components` or of the `sprites` / `files` tables; a getter on
139
- `Transform`, on `Shape.solid`, or on `actor.components` itself; a stored
140
- field redefined as a getter after the engine has read it; an object's
141
- local `matrix` written by hand while its `matrixAutoUpdate` is on (set
142
- `position` / `quaternion` / `scale` instead); three.js private fields
143
- written directly (`rotation._order`, `quaternion._x`).
144
- - `"engine": { "dropEmptyParts": true }` at the scene file's top level (the
145
- same `engine` object) asks the engine to place models without the groups
146
- that draw nothing. A placed model is a game build: its meshes are merged
147
- into a few draw calls, but every part keeps its own three.js group, most of
148
- them then empty, and three.js and the engine visit every object under the
149
- scene on every frame. A town of a few hundred models is two thirds such
150
- groups. The terms:
151
- > With the key absent, a model is built and placed exactly as before: the
152
- > same objects, the same shared build, the same node. With the key present,
153
- > every object that is drawn (a mesh, its outline, anything that is not a
154
- > plain group) is the same object with the same geometry, material and
155
- > world matrix as without it, on every frame, and walks, `motion`, clips and
156
- > glow play the same. What a deck must not rely on under the key is finding
157
- > the group of a part that draws nothing unless that part is one that
158
- > stays.
159
-
160
- What goes: a group with nothing drawn on it or anywhere under it -- no
161
- mesh, line, points, sprite, light or camera. That includes the group of a
162
- part that IS drawn when its mesh was merged into a batch on the model's
163
- root or on a moving part: the picture keeps the part, `modelParts` does
164
- not. What always stays, with every group above it:
165
- - a part marked `keep: true` (docs/pxmodel-format.md: "for a deck that
166
- reaches for it by id"), with its own mesh as before;
167
- - a part named `slot-...`. The format's docs let a deck "parent your own
168
- parts to it", and nothing says that happens only in the model file, so a
169
- slot is never dropped: a deck may hang a mesh on one at runtime and it is
170
- drawn where it would be without the key;
171
- - a part the walk moves (`legL`, `legR`, `armL`, `armR`, `torso`) or the
172
- model's `motion`, gait or `clips` move, drawn or not, and every copy of
173
- one;
174
- - anything a kept part or slot holds that is not another part.
175
-
176
- An actor whose model draws nothing at all (an invisible collider placing an
177
- empty model) gets no rig group under its node: the node is there, with
178
- `userData.modelParts` an empty Map and no children.
179
- So under the key:
180
- - `scene.three.nodes.get(id).node.userData.modelParts` holds only the parts
181
- that stayed. `modelParts.get('door')` for a part that draws nothing and
182
- is none of the above is `undefined`, where without the key it is an empty
183
- group. To reach for an empty part as a locator (a muzzle, a hand), mark
184
- it `keep: true` or name it `slot-...`; it then stands exactly where it
185
- did.
186
- - code that walks a node's tree counts fewer objects, and a node's first
187
- child is its rig only when its model draws something.
188
- - nothing else changes: which actors have nodes, `userData.actorId`, the
189
- rig's `yOffset` and `scale`, physics, picking, shadows (casters are
190
- culled by their own meshes' bounds), `instanceModels`.
191
-
192
- It is read when the scene loads, as `skipUnchangedActors` is, and each
193
- scene decides for itself: a node and a shared model build made for a scene
194
- that asked are never used for one that did not, or the other way round (a
195
- resident scene parked while another plays, a pack mounted in a town, a door
196
- trip, a scene file reloaded with the key changed -- every node is then
197
- built again). The scene editor and the play panel draw a scene through the
198
- same engine, so both follow the scene's key; the editor selects actors, not
199
- parts, and is not affected. The model editor and `npm run render` build a
200
- model for themselves, with every part's group, whatever any scene says.
201
- Opt in with `skipUnchangedActors` when a scene is hundreds of placed
202
- models; a scene of a few gains nothing.
203
- - `"engine": { "skipEmptyNodes": true }` at the scene file's top level
204
- keeps an actor with no children on its three.js node outside the play scene.
205
- Empty markers, anchors and triggers then cost no scene object. A missing or
206
- invalid Model with no Shape is empty; a Model that builds a rig is not,
207
- even if its rig draws nothing. With `dropEmptyParts`, a model reduced to no
208
- rig is empty too. The key is read on load, and only exactly `true` opts in.
209
- Without it, nodes, signatures and shared model caches are exactly as before.
210
- A player whose scenes never ask creates no mode record, system or listeners.
211
- The player arms the mode only
212
- after a keyed scene has finished loading; syncs never arm it. The scene
213
- editor always keeps its nodes.
214
-
215
- `scene.three.nodes` keeps every entry and its usual Group/ActorNode, with
216
- position, rotation and world matrix placed by the engine even while detached.
217
- Move an empty actor through its Transform (or physics), not by writing the
218
- detached node's position, quaternion, rotation or scale directly: those
219
- writes are outside this key's contract and do not update its world matrix
220
- until the node has a child and is attached again.
221
- No transform properties or methods are wrapped. Adding a
222
- child queues attachment at the next actor sync; removing its last child
223
- queues detachment there too, after three.js event dispatch completes.
224
- Build and child events queue classification for the next outermost sync;
225
- listeners only mark dirty, and syncs inside event dispatch defer the queue.
226
- Dispatch depth unwinds even if a listener throws. A load, reset or disposal
227
- invalidating a pass aborts it before any further placement or attachment.
228
- Settled frames scan no nodes.
229
- Only detached empty nodes whose pose changes receive a matrix update; a
230
- settled static empty actor needs none. Load/reset gives nodes back before
231
- the next scene runs, leaving keyless sync on its original path.
232
- Gaining or losing a Model/Shape follows the usual look rebuild, including
233
- spawn, reload, resident scenes and `staticActors` (call `scene.touch` before
234
- changing a static actor, as usual). A node deliberately hidden or reparented
235
- by a consumer stays under that consumer's control. Low-tier bounds and
236
- hiding, avatar parts and attachments keep using the same entries. Traversing
237
- the play scene excludes empty actors; traverse `scene.three.nodes` to find
238
- all actors. If the scene itself has a transform or a parent, nodes stay
239
- attached so world-space reads retain that transform.
240
- - `"engine": { "staticActors": true }` at the scene file's top level (the same
241
- `engine` object), in a scene that also sets `skipUnchangedActors`, asks the
242
- engine to leave alone the actors the scene file marks as scenery:
243
- `"static": true` on the actor, beside its `id` and `components`. With
244
- `skipUnchangedActors` the engine still asks, of every actor on every frame,
245
- whether anything it is drawn or simulated from has changed; for a town that
246
- is mostly buildings, that asking is a quarter of a slow phone's frame. A
247
- marked actor is not asked. The terms:
248
- > With the key absent, or without `skipUnchangedActors`, a scene runs the
249
- > engine exactly as before, whatever its actors are marked. With both, a
250
- > marked actor that is still is drawn and simulated exactly as it was on the
251
- > last frame the engine looked at it, until the engine is told it is being
252
- > changed: `scene.touch(actorOrId)`. From the frame of the touch on, the
253
- > actor is an ordinary one, followed as every actor is under
254
- > `skipUnchangedActors`, until the next scene load. **A change to a marked
255
- > actor made without `scene.touch` is not followed**: a component's field
256
- > written, a component added, removed or switched off (`$enabled`), its
257
- > node or any object under it moved, hidden or given children. Nothing in a
258
- > published deck notices such a write.
259
-
260
- This is the one `engine` key under which "nothing has to be marked dirty"
261
- stops being true, and only for the actors a scene marks. Mark what nothing
262
- ever writes; touch before writing anything else.
263
-
264
- Only actors are marked. What the engine draws that is not an actor -- the
265
- sun and its shadow camera, the camera, a sky the engine itself draws from
266
- an `engine` key -- has no `static` to carry and is not
267
- part of the still set: it is drawn and moved as it always is, every frame,
268
- whatever the scene marks. A sky that IS an actor (one `Model` on a
269
- `Transform`, as the hub town's is) is marked like any other scenery.
270
-
271
- Which marked actors are still. A marked actor is still when it was in the
272
- scene file at load (a spawned actor never is), has no `Body`, none of its
273
- components' classes has an `update`, `onEnable` or `onDisable`, its model
274
- does not walk or move inside itself (the engine finds that out when it has
275
- built the node, and touches the actor itself), and nothing has touched it
276
- since the load. Any other marked actor is an ordinary actor; the mark costs
277
- nothing. `scene.stillActors` is the Set (null in a scene without the key).
278
-
279
- What tells the engine, so a deck does not have to:
280
- - `scene.despawnActor`, `scene.load` / `loadFromFile` / `setContent`,
281
- `scene.setBehaviors` (the still set is reckoned again; what was touched
282
- stays touched);
283
- - `scene.physics3d.setVelocity`, `applyImpulse` and `addForce` touch the
284
- actor they are handed. `bodyOf` does not: asking for a body is not a
285
- change, and a marked actor's body made dynamic or kinematic through it
286
- needs a `scene.touch`;
287
- - the multiplayer-3d kit touches an actor before it writes a network pose
288
- on it, and hub-game before it hides, shows or tints an actor or swings a
289
- door (`hub.hide`, `hub.show`, `hub.tint`; `hub.move` arrives as a network
290
- pose), so a place's server may do those to a marked actor;
291
- - what marked actors share is watched for all of them at once, and followed
292
- with no touch: a model file edited (or a file or art it reads), art that
293
- finishes loading, the look switched, the scene itself
294
- (`scene.three.scene`) moved, turned or scaled.
295
-
296
- A behaviour, a collision callback or any other deck code that writes
297
- another, marked actor calls `scene.touch(id)` first; it is a Set delete,
298
- safe to call every frame and on any actor, and does nothing in a scene
299
- without the key. `scene.touch` exists on every scene, so code that may run
300
- under an older kit calls `scene.touch?.(id)`.
301
-
302
- What "left alone" means, frame by frame. A still actor is not visited by
303
- `scene.update` (it has nothing to update), by the pass that builds and
304
- places nodes, or by the physics pass (its body is fixed and where it was
305
- put); and its node's `updateMatrixWorld` returns at once, so its matrices
306
- are not recomputed or even compared. three.js still walks its objects to
307
- cull and draw them, and rapier still collides with its body. So:
308
- - `scene.getActors()`, `getActor`, `actorWith` and the node map
309
- (`scene.three.nodes`) are unchanged: a still actor is in all of them, with
310
- its node, and the node's `position` is its Transform's;
311
- - a still actor's node may be taken out of the scene and put back under the
312
- same parent by deck code (hub-game's low picture does, by distance): it
313
- comes back drawn where it was, with no touch. Putting it under another
314
- parent is a change to it;
315
- - a frame on which the still set changes (a touch, a despawn), and the one
316
- after, visit every actor once, as a frame under `skipUnchangedActors`
317
- alone does, before the rest are left alone again; so does a frame on
318
- which a node is built, rebuilt or released. Touching a different actor
319
- every frame gives the key's saving away: such actors should not be
320
- marked.
321
-
322
- Where the key does nothing: without `skipUnchangedActors`; in the scene
323
- editor, which changes actors as it pleases; and in a world with
324
- `instanceModels` on. In a scene with a
325
- `scene.three.scene.userData.groundHeight` callback no node is frozen (every
326
- pass there runs the old way, as under `skipUnchangedActors`), though still
327
- actors are still left out of `update` and the physics pass.
328
-
329
- How it stays right (`engine3d/world3d.js` has the rule and the code):
330
- > A pass is ordinary (every actor, as the skipping pass runs it) unless the
331
- > still set and the things its actors share read as they did when the last
332
- > ordinary pass that ended alone adopted them; then a still actor is left
333
- > exactly as that pass left it.
334
- >
335
- > The still set is adopted only after an ordinary pass has completed
336
- > without throwing. While any ordinary pass, or anything a pass calls back
337
- > into, is running, nothing is frozen and no still state is trusted. Any
338
- > interruption leaves the next pass ordinary.
339
-
340
- The second paragraph is one mechanism, used the same way in the three
341
- places that leave still actors out (the runtime's `update`, the pass that
342
- places nodes, the physics pass): each has a keeper
343
- (physics-2d `engine/stillClock.js` `StillKeeper`) that counts every entry
344
- into its pass, settled or ordinary, by any runtime, nested or not. A pass
345
- may be settled only on an adoption made, or last confirmed, at the count
346
- as it stood just before the pass entered, for the very version of the still
347
- set the runtime has now; otherwise the adoption is dropped there, before
348
- the pass does anything. A new adoption is recorded only at the very end of
349
- the whole operation (for `update`: after the behaviours and every system;
350
- for the physics pass: after the step, the write-back and the collision
351
- callbacks), and only if the pass returned, nobody else entered, and the
352
- still set is unmoved. Nothing is ever put back. So code that walks, draws,
353
- syncs or updates the scene from inside a pass, settled or not, sees what
354
- it sees without the key; a behaviour, a system, a node being built or
355
- released, rapier's step or a collision callback that throws leaves nothing
356
- adopted; and a pass entered from inside another, by the same runtime or a
357
- different one, whether it returns or throws and is caught, leaves the pass
358
- around it unable to adopt, and the next pass ordinary. The keeper of a
359
- world, and of a physics system, sees every pass of every kind from the
360
- moment it exists, not only those of scenes that ask: a scene without
361
- `skipUnchangedActors` played on the same world or the same physics system
362
- (a pack mounted in a town, a callback that syncs another scene) drops what
363
- was adopted when it enters and adopts nothing.
364
-
365
- World disposal, standalone ground replacement, physics-debug updates,
366
- resizing and the editor's orbit-lens return are counted for their whole
367
- duration by `outsideCall`: `keeper.begin(NOT_STILL)`, adoption dropped and
368
- nodes thawed, then `keeper.end(pass, false)` in a `finally`. While this pass
369
- is running, no listener's nested sync can adopt or freeze, including between
370
- two listeners or two disposable targets. Near shadows use the same bracket
371
- across both map and blur-map disposal, only when a non-null map is released
372
- (a fit size change, mode leave, or world disposal). Their callback is made
373
- once per world and reused across frames and mode recreation. Unchanged
374
- near-shadow frames keep their adoption and frozen nodes. The sky uses the
375
- same bracket for each record release (prepare, settle, load or world
376
- disposal), across every texture, geometry and material listener, and for
377
- the textures shed after a step. Its callback is acquired only when a sky
378
- record is made, stored on the world and reused by later records. Unchanged
379
- sky frames keep their adoption and frozen nodes. On return or throw
380
- the bracket exits with nothing adopted; the next actor pass is ordinary and
381
- later passes may settle. A disposed world never adopts again.
382
- World disposal returns the orbit lens, releases the sky, drops near shadows
383
- and disposes nodes in that order, each cleanup in the previous one's
384
- `finally`. All four run even if the lens or an earlier listener throws;
385
- the first thrown value wins, including a falsy value such as `0`.
386
- Sky preparation reads engine art through own data-property descriptors,
387
- never through an accessor, so these reads need no call-out bracket and do
388
- not drop static adoption on unchanged frames.
389
-
390
- Before a world has a keeper, `outsideCall` uses `world.unkept` exactly as a
391
- plain `syncActors` pass does: increment before the operation and decrement
392
- in a `finally`. A keeper made by a listener sees this count, so none of its
393
- nested passes can settle or adopt while the operation runs. On exit, if a
394
- keeper was made, its adoption is dropped and nodes thawed again, leaving
395
- the next pass ordinary even when the operation throws.
396
-
397
- Key-absent inventory of the added statements at these call-outs: with no
398
- `stillKeeper`, `disposeWorld` and `resizeWorld` each add a keeper test, an
399
- `unkept` increment, a `try/finally`, a decrement and an exit keeper test;
400
- `updatePhysicsDebug` does the same when buffers exist, `syncGround` when
401
- the ground changes, and the editor's orbit-lens return when a lens exists.
402
- Near shadows add no keeper test or new callback allocation on an unchanged frame:
403
- they reuse the world's lazy callback. A release adds the same `unkept`
404
- bracket for the entire operation, only when a map or blur map exists. The
405
- sky allocates its callback only for an actual sky record: a world that never
406
- has one makes none. Unchanged sky frames do not test or call the hook; a
407
- record release or a nonempty shed-texture disposal adds the same bracket.
408
- Rare operations pass a closure to `outsideCall`; with no keeper it runs
409
- inside this count. Only a keeper made during the call adds `dropStill` on exit.
410
- None makes a keeper with the key absent.
411
-
412
- The runtime keeps the still set and a number that moves whenever the set
413
- changes (`scene.stillActors`, `scene.stillVersion`; one sequence of
414
- numbers for every scene, so no two states share one); the world and the
415
- physics system each keep the number they adopted, and a pass decides from
416
- its own runtime, at its start, whether it may leave anything out. A node is
417
- frozen by two numbers on it, matched against one on the world that only
418
- ever moves on, so every frozen node of a world thaws at once with nothing
419
- to visit. Between passes a frozen node guards itself, on every walk of the
420
- scene, whoever walks it: it is frozen only while no scene's still set has
421
- changed since it froze (so `scene.touch` thaws at once: an actor touched
422
- and then posed by its node is followed by the very next draw), and only
423
- while it is under the parent it froze under and that parent's world matrix
424
- is the one three.js has just computed for it (so the scene moved, by its
425
- position, its matrix written by hand, or a parent of its own, is followed
426
- by the next walk).
427
-
428
- For QA, never in play: `scene.three.auditStatic = n` checks `n` still
429
- actors a frame, in turn, the way an ordinary frame would have (and every
430
- still body), writes what it finds changed to
431
- `scene.three.staticAuditFailures` as `{ id, what }`, warns once an actor,
432
- and touches it. Set it to `Infinity` to check every still actor every
433
- frame: a deck that marks actors should be played that way once with
434
- nothing reported.
435
- Opt in when a scene is hundreds of actors that are never written; a scene
436
- whose scenery is a dozen actors gains nothing.
437
- - `"engine": { "shadows": { "distance": 40 } }` at the scene file's top level
438
- (the same `engine` object) asks the engine to draw the sun's shadows where
439
- they can be seen, near the camera, rather than in the sun's fixed box.
440
- Without it the sun's shadow camera is a fixed 150 x 120 m box round the
441
- origin, so every caster under the box is drawn a second time each frame
442
- wherever the player stands, and a scene larger than the box has no shadows
443
- outside it. The terms:
444
- > With the key absent, a scene is drawn exactly as before: the same shadow
445
- > camera, map, `castShadow` flags and render calls. On a frame the mode
446
- > draws, everything the camera sees within `distance` metres (measured along
447
- > the way it looks) is shadowed as it would be under a box that covered it,
448
- > with texels exactly the size the sun's own are and the same softness and
449
- > bias. Shadows are complete out to `distance` for casters inside the depth
450
- > range below; a point farther off may or may not be shadowed, and nothing
451
- > cuts shadows off there.
452
-
453
- Past `distance` on a frame the mode draws, a point may or may not be
454
- shadowed (a caster kept for a nearer point shadows farther ones too), and
455
- past the edge of the mode's box nothing is: three.js leaves a point
456
- outside the shadow map lit, and the sun's own shadow is not drawn on such
457
- a frame. Under a fixed camera looking down that edge is off screen.
458
-
459
- Under the orbit camera key as well (below), which tilts the camera to the
460
- horizontal where that edge would be a hard line across the ground, a frame
461
- the mode draws fades the sun's shadow out toward it
462
- (`engine3d/shadowfade.js`): whole up to 0.75 of the mode's reach (the
463
- distance it could fit, along the way the camera looks), gone at the reach,
464
- smoothstep between, to full sun, which is what lies beyond. How:
465
- > The fade writes no material, not even for a moment, and the scene's,
466
- > the faded meshes' and the faded materials' own callbacks never meet a
467
- > variant. What gets one: a material whose class is exactly one of
468
- > three's own lit ones (standard, physical, lambert, phong, toon; a
469
- > subclass is not faded), alone on its mesh (a mesh with an array of
470
- > materials is not faded), whose hooks, listeners and mesh are plain
471
- > data (read from property descriptors: one behind a deck's accessor is
472
- > not faded, and the fade never calls a getter), and whose `onBeforeCompile`,
473
- > `customProgramCacheKey` and `onBeforeRender` are three's own or the
474
- > kit's (`engine3d/kithooks.js`: look.js, optimize.js,
475
- > materialpresets.js), on a mesh that receives shadows and has no
476
- > `onBeforeRender` or `onAfterRender` of its own; and a frame is faded
477
- > only when the scene has no `onBeforeRender` of its own. Anything else
478
- > is drawn as it is, unfaded. A variant is a separate material object to
479
- > the renderer whose every property, read or written, is the original's:
480
- > its prototype, shared per material class, has a forwarding accessor for
481
- > each property and accessor of the class, over a proxy that answers
482
- > anything else from the original; so deck code inside the frame that
483
- > reaches a variant (an LOD's `update`, a callback installed mid-frame and
484
- > handed the material three listed) and three's own side flip and version
485
- > bumps write the original as they would without the key. Its events and
486
- > `dispose` are the original's too; only the renderer's own dispose
487
- > listener for the variant's program (known by its function, learned
488
- > once per renderer by compiling a private material and finishing its
489
- > program's first-use initialization before disposing it) is held by the
490
- > variant (and added to
491
- > the original, where the renderer drawing it would have it), and the
492
- > variant's program is let go of when the variant is disposed or dropped
493
- > or the original is disposed (seen by a dispose listener gone from the
494
- > original, or by the renderer's own entry for the original replaced,
495
- > when the world's renderer also draws it elsewhere). Its own: an id, that listener, and the
496
- > shader hooks held as they were when it was made (the held
497
- > `onBeforeCompile` then the fade; the held key plus
498
- > `|near-shadow-fade`). Before each faded frame it is drawn in it is
499
- > dropped if the original has other hooks or is no longer one to fade. A
500
- > hook the original is given inside a frame is never run for the
501
- > variant: it compiles with the held hook under a key of its own and is
502
- > dropped next frame. A property defined on a variant reaches the
503
- > original after the frame; deck code that compares a variant by
504
- > identity with its original, asks it `key in` or deletes through it sees
505
- > another object. The fade's
506
- > uniform is on the variants only. The variants go on the meshes right
507
- > before the mode's one render call, and come off in a hook on the world
508
- > renderer's `shadowMap.render`, which three calls on every render after
509
- > listing the draws and before drawing any, whatever the shadow
510
- > settings; the hook comes off when the sun gets its own shadow back,
511
- > whatever the render did (one a deck replaced meanwhile stays replaced,
512
- > and ours, if it still calls it, only calls the pass it had). So the
513
- > frame's own draws use the variants and every render after its list of
514
- > draws sees the originals. Accepted, inside the keyed world's own frame
515
- > only: a deck's own sort comparator (`renderer.setOpaqueSort` /
516
- > `setTransparentSort`) is handed render items holding the variants. A
517
- > variant not drawn for 60 faded frames is disposed; all are disposed on
518
- > a scene load, an editor frame, any frame of a scene without both keys
519
- > and `disposeWorld`. The fade is for the first casting directional
520
- > light, and a frame is faded only when that is the sun. Not covered: a
521
- > hook or callback that changes in place an object the original holds by
522
- > reference (its colour, a texture, its defines) changes it for every
523
- > world, as it would without the key. A material that is itself a Proxy
524
- > can observe the fade's reads through its traps. Deck getters with side
525
- > effects on properties three reads during a render (`isMesh`, `visible`,
526
- > `children`, `matrixWorld`, `layers`, ...) may run extra times in a
527
- > faded frame. A mesh whose `material` is not its own writable,
528
- > configurable data property (read-only, an accessor, or inherited from
529
- > its prototype) is drawn unfaded, and so is a frame whose
530
- > renderer's `shadowMap.render` cannot take the hook (it goes on before
531
- > any variant does). A deck that makes `shadowMap.render` read-only
532
- > during a keyed frame has it put back (redefined) if it is still
533
- > configurable; one it also makes non-configurable keeps the fade's
534
- > hook, inert from then on: it only calls the pass it had. A deck
535
- > setter on a mesh's `material` that throws when the material is put
536
- > back holds that mesh, as below. Giving the meshes their materials back is total:
537
- > each mesh on its own. A deck that redefines or locks its own mesh's
538
- > `material` during a keyed render gets the best the fade can do without
539
- > calling its getter: a data property made read-only but configurable
540
- > is redefined with the deck's attributes and the original's value; an
541
- > accessor with a setter has the original set through it once; anything
542
- > else (read-only and not configurable, an accessor without a setter)
543
- > keeps its variant, which reads and writes the original, and is tried
544
- > again at every frame boundary while the fade lasts. Once the fade is
545
- > dropped such a variant is inert: it keys and compiles exactly as its
546
- > original, so later keyless frames draw the original's program. Its
547
- > programs are not freed by a later `dispose()` of the original (that
548
- > would take a listener on the shared material): on such a mesh only,
549
- > each dispose and recompile leaves one program behind.
550
- > Two more limits, inside the keyed world's own frame: a variant's
551
- > properties live on its prototype (the forwarders), so deck code run
552
- > during that frame (an LOD's `update`, a draw callback) that copies a
553
- > mesh's material with a spread, `Object.keys` or own-property checks
554
- > sees none of them, and whatever it writes from that copy differs from
555
- > without the key (on a material shared with a keyless world, that world
556
- > draws the write too). And a deck that defines a read-only, non-configurable
557
- > property on one of three's own material prototypes, then shadows it on
558
- > a material, makes a read of that property through a variant throw a
559
- > `TypeError` (the forwarder is a Proxy, which must report the
560
- > prototype's value). Neither happens in a world without the keys.
561
-
562
- Without both keys nothing of this runs: the same materials, programs,
563
- program keys, shader sources and draws as before
564
- (scripts/test-orbit-shadow-fade.mjs, on three.js's own WebGLRenderer over
565
- a context that draws nothing, also with a keyed and a keyless world
566
- sharing materials). Under both keys the first faded frame compiles one
567
- program per distinct lit program in view (a hitch, once), and each faded
568
- frame walks the scene's visible objects and swaps each receiving lit
569
- mesh's material twice, and three reads each variant's properties through
570
- the forwarders. In node over a context that draws nothing, 500 receiving
571
- meshes on 40 materials take about 2.7 ms a frame with the fade against
572
- about 1.8 ms with near shadows alone (the JavaScript side only).
573
-
574
- The depth range is the sun's own `near` and `far` along the light, measured
575
- from the engine's shadow camera, which stands as far from the middle of the
576
- view's sphere (taken along the light to the height of the sun's target) as
577
- the sun does from its target. For the engine's sun (19.9 m from its target,
578
- near 0.5, far 50) that is casters up to 19.4 m toward the sun and 30.1 m
579
- away from it, from the ground under the middle of the view. It is what the
580
- sun's own camera draws for a view round its target: there too a caster 25 m
581
- up the light from a point on the ground is not drawn.
582
-
583
- How it stays out of the scene's way (`engine3d/nearshadows.js` has the rule
584
- and the code):
585
- > The scene's sun, its shadow object, its shadow camera, its map and its
586
- > target are never written by this mode. What the mode needs is its own
587
- > objects, attached only for the duration of one renderer.render call
588
- > inside try/finally. Outside that call the world is as main leaves it, so
589
- > there is nothing to restore on a scene change, a throw, a dispose or a
590
- > keyless frame.
591
-
592
- Who the key is for:
593
- > The key is for a scene whose deck leaves the renderer's shadow settings
594
- > and the drawing of the world to the engine. A deck must not set the key if
595
- > any of its code, in any scene played in the same world, changes
596
- > renderer.shadowMap.type, .enabled, .autoUpdate or .needsUpdate after the
597
- > world is made; calls renderer.render or the composer itself, inside or
598
- > between the engine's frames; calls renderWorld from inside a frame; or
599
- > gives the world's renderer to another world. In a deck that does, shadows
600
- > may be drawn wrongly with the key, and three.js's shadow bookkeeping for
601
- > the sun's own map (its filter, its size) may differ from a world that
602
- > never had the key until the world is disposed. A deck that never sets the
603
- > key is unaffected whatever it does.
604
-
605
- (three.js keeps the shadow pass's state, the type it last drew with and the
606
- frustum it culls by, inside the renderer, where the engine can neither read
607
- it nor put it back. Nothing in the kits does any of the above after
608
- `makeWorld3D`.) Nothing of the renderer's is ever written by the mode.
609
- (With the orbit key as well, the far-edge fade below puts a hook on the
610
- world renderer's `shadowMap.render` for the one render call, and takes
611
- it off after.)
612
-
613
- Within that, the mode draws a frame only when all of these hold; otherwise
614
- the frame is drawn exactly as without the key. They are cheap protection,
615
- looked at every frame, not promises about a deck outside the condition
616
- above. After any `renderWorld` call returns, either the mode drew that
617
- frame or nothing of the mode's is allocated: every way out of the mode (a
618
- frame drawn plain for any term, a re-entry, a throw, a dispose) frees its
619
- map at that moment:
620
- 1. the scene now playing asked, with a finite distance above 0
621
- (`runtime.nearShadowDistance`, read when the scene loads), the frame is
622
- the player's (the scene and model editors give `renderWorld` no runtime),
623
- and the world is not being disposed;
624
- 2. `renderWorld` was not entered from inside another `renderWorld` of this
625
- world that had anything of the mode's to do, keyed or not, and no frame
626
- of this world has been entered that way before. The call inside is drawn
627
- plain; the sun has its own shadow back before that call draws, and still
628
- has it when the call returns, whatever the call did, disposing the world
629
- included; the mode is off for this world from then until the world is
630
- disposed (`world.nearShadows.off`); and the frame that was re-entered,
631
- whose map is freed under it, may have wrong or missing shadows, that
632
- once;
633
- 3. read at the start of the frame, `renderer.shadowMap.type` is
634
- `PCFSoftShadowMap` and `.enabled` and `.autoUpdate` are on, which is how
635
- the engine makes the renderer; and the frame before was also a frame
636
- with the key that found the same and was drawn to the end
637
- (`world.nearShadows.lastType`). So the first frame with the key, after a
638
- load or after any frame without it, is drawn plain, and three.js
639
- allocates and configures the sun's own map as it would have; and so is
640
- the frame after one that threw, and after one the mode drew that ended
641
- with no map on the engine's shadow (three.js drew nothing: a lost
642
- context). The engine's shadow never has a blur map;
643
- 4. the sun (`world.sun`, the light whose bias the engine fits) is still a
644
- child of the scene, is the first directional light there that casts, has
645
- `castShadow` on, is visible and on the camera's layers, and its own
646
- shadow is a directional light's, has `autoUpdate` on and has its map.
647
- Looked at every frame: a sun removed or replaced means plain frames, in
648
- which a replacement draws its own box as without the key;
649
- 5. the camera is a perspective camera, and the sun's own box and map size
650
- give a texel size: its shadow camera has zoom 1 and no view offset.
651
-
652
- All of the mode's work in a `renderWorld` call (deciding the terms, fitting
653
- the bias, allocating, swapping, rendering, leaving, disposing) happens
654
- inside one outermost try/finally, counted on the world
655
- (`world.nearShadows.depth`). A call that arrives while the count is up
656
- draws plain, puts the mode off and makes nothing. The finally establishes
657
- the postcondition itself: unless the mode drew this frame to the end, on a
658
- world not disposed, with the mode not off and a map on its shadow, nothing
659
- of the mode's is allocated and the sun has its own shadow. Its order is
660
- what makes that hold through a `dispose` listener that throws: first the
661
- sun gets its own shadow back (an assignment, which calls no one), then what
662
- is freed is detached and only then disposed, and looked at again after the
663
- callbacks; the count comes down in a finally of its own that nothing skips.
664
- A world with no mode state playing a scene without the key does not enter
665
- any of it: `renderWorld` runs its two statements (fit the bias, render)
666
- with no counter and no try, as it always did.
667
-
668
- On such a frame `renderWorld` fits the bias of the sun's own shadow as
669
- always, puts the engine's shadow on the sun (`sun.shadow`), renders, and
670
- puts the sun's own back in a `finally`; that assignment is the only write,
671
- and it is undone only by the frame that made it (a frame that finds the
672
- world disposed, its state replaced or itself re-entered touches nothing).
673
- three.js keeps nothing per shadow object (the shadow pass and the light
674
- uniforms read `light.shadow` afresh every render), so the next plain render
675
- reads the sun's own as if nothing had happened. The engine's shadow
676
- (`world.nearShadows.shadow`, a DirectionalLightShadow with its own camera,
677
- map, matrix and frustum), each frame:
678
- - looks along the sun's direction, from as far as the sun is from its
679
- target, with the sun's own near and far, round the smallest sphere that
680
- holds the camera's view out to `distance`: one size whichever way the
681
- camera turns (it changes only with the canvas's shape or the camera's
682
- lens). It sits a whole number of texels along each of its axes, so a
683
- shadow's edge does not crawl as the camera moves. The light does not move;
684
- - has texels exactly the size of the sun's own (the sun's box over its map
685
- size, read each frame), so its box is `map size x texel` and it copies the
686
- bias `fitShadowBias` fitted to the sun's own, with its intensity and
687
- radius: 40 m on a portrait phone is a 710 x 888 map. Its map is never
688
- larger than the sun's own in area (2048 x 2048) nor than the renderer's
689
- largest texture on a side; a `distance` that would need more is drawn as
690
- the largest that fits (about 100 m in portrait, 38 m at 32:9) rather than
691
- with larger texels;
692
- - hands three.js a frustum to cull casters with (`getFrustum`) that is its
693
- box narrowed to the view's outline, out to `distance`, as the sun sees it,
694
- pushed out by everything three.js's shader moves a shadow lookup by across
695
- the light: the normal bias drawn with that frame (the lookup is made at
696
- `position + normal * normalBias`) and four texels for the soft filter's
697
- taps. The box is wider by the same. Every caster whose shadow
698
- can land on something the view sees within `distance` is drawn into the
699
- map; one whose shadow cannot is not. No `castShadow` flag is changed and
700
- nothing is cached: every caster that is drawn is drawn every frame, so a
701
- moving thing's shadow moves with it as before.
702
-
703
- A frame without the key drops what the mode holds, all but `off`;
704
- `disposeWorld` drops it all. The engine's map (and a blur map, were there
705
- one) is taken off its shadow before it is disposed, once.
706
-
707
- What a deck that works on the sun sees under the key: the sun's own
708
- `shadow.camera` box, `mapSize` and any `getFrustum` of its own are left as
709
- they are and not used for drawing on the frames the mode draws (a sun whose
710
- `shadow.autoUpdate` the deck turned off gets plain frames, term 4),
711
- except that the box over the map size gives the texel size and `near`/`far`,
712
- `bias`, `normalBias`, `intensity` and `radius` are copied each frame;
713
- three.js does not draw the sun's own shadow on those frames, so its map and
714
- its shadow camera's matrices stay as the last plain frame left them; a sun
715
- moved or re-aimed is followed (its direction is read each frame). Without
716
- the key such a deck works exactly as before. What differs on screen with
717
- the key: shadows no longer end at the fixed box's edge, so a scene larger
718
- than that box gains shadows where it had none; beyond `distance` from the
719
- camera they thin out and, past the engine's box (which reaches somewhat
720
- farther than `distance`), end, with a hard edge if the camera can see that
721
- far (pick a distance past the ground the camera can see). Opt in when a
722
- scene is wide enough that most of its casters are out of sight; a scene
723
- that fits the view gains nothing.
724
- - `"engine": { "camera": { "follow": "rigid" } }` at the scene file's top
725
- level (the same `engine` object) asks the `Player` behavior for a follow
726
- camera that moves with the player instead of easing after it. Without it
727
- the camera eases its whole position toward its place behind the player, so
728
- how far it trails a walking player depends on how long each frame is: on
729
- frames of uneven length (a page missing every other vsync) the distance
730
- changes every frame and the view judders, which reads as an up-and-down
731
- shake walking forward, since the camera looks down. The terms:
732
- > With the key absent, the camera is placed exactly as before: the same
733
- > code, in the same place in the frame. With the key present, the camera's
734
- > offset from the player (its angle and height) and the player's height are
735
- > eased at the rate the old camera eases, with an easing that trails a
736
- > steadily moving target by the same distance however the frames are cut;
737
- > the player's ground position is not eased. So a steady walk leaves the
738
- > player at one place on screen, a turn swings the camera round as before,
739
- > and a jump lifts the player on screen while the camera follows smoothly.
740
- > A teleport (more than 3 m in a frame, or the camera more than 20 m off)
741
- > still snaps it, and it still looks at the player.
742
-
743
- Where it is placed: behaviors run before physics, so the Player sees the
744
- position the last frame drew. Under the key it asks for its camera instead
745
- (`scene.followCamera`: its actor id and the scene data it asked in), every
746
- frame, whether physics is ready or not, and the physics system places it
747
- last in its `afterBehaviors`, after this frame's positions are written back
748
- and the collision callbacks have run, on the position the frame is drawn
749
- with; on a frame physics cannot step (rapier still loading, or the first
750
- frame after a load) it is placed all the same. The player is looked up as
751
- the scene has it then: one a callback despawned gets no camera, and a
752
- request made before a load is not used after it (a load and a dispose drop
753
- it). Systems registered after physics (the hub's) see the camera already
754
- placed. The offset is read each frame from where the camera is, against
755
- the point it followed the frame before, so a camera something else placed
756
- (a hub trip's camera, a cutscene) is eased on from wherever it was put.
757
- The play panel and a published deck play the scene through the same
758
- runtime, so both follow the scene's key; the scene editor's own orbit
759
- camera is not a follow camera and is not affected.
760
-
761
- The key means "the player is held steady on screen", so it also changes
762
- how the `Player` hovers. Without it the hover spring (and the fall-faster
763
- pull) is an impulse, pushed once per drawn frame, while gravity pulls once
764
- per fixed 1/60 physics step, and a frame takes none, one or two steps: on
765
- a frame that is not exactly one step the player is kicked up or let drop,
766
- a bob of 0.6 to 2 cm walking on a phone, which a camera that holds the
767
- player still would show as the whole view bobbing. The terms:
768
- > With the key absent, the Player makes the calls on `scene.physics3d` it
769
- > made before, with the same arguments, in the same order. With the key
770
- > present, the hover and the fall-faster pull are forces
771
- > (`scene.physics3d.addForce`), which act once per physics step as gravity
772
- > does: walking on flat ground the player's height does not move, whatever
773
- > the frame lengths. The spring is the same one (160 and 18), resting
774
- > 1.38 cm higher (`STEADY_REST`) so that the kit's player (gravity scale
775
- > 2) stands where it does without the key, 0.7412 m, to within 0.01 mm; a
776
- > jump reaches 2.348 m (2.347 on alternating frames) where without the key
777
- > it reaches 2.347 to 2.354 m depending on the frames. A player with
778
- > another gravity scale stands 0.69 cm per unit of scale off its keyless
779
- > height. The walk push is an impulse either way (it leaves the height
780
- > alone, and the rigid camera does not show its unevenness).
781
-
782
- The rule for forces: **a force is for the frame it was asked in.** rapier
783
- keeps a force on a body until it is reset, so nothing outside the physics
784
- system puts one on a body. `addForce(actor, v)` writes down what was asked
785
- (asking again in the frame adds; `resetForces(actor)` drops it: the
786
- Player does that on the frame of a jump, or the frame's lift would add
787
- 11 cm to it); the physics pass puts the forces on their bodies just before
788
- the frame's fixed steps and takes them off straight after, in a `finally`
789
- (`stepForced`, systems/physics3d.js), however many steps there were. So
790
- between frames no body carries a force, and each of these leaves none: the
791
- Player not running (turned off, physics not ready) asks for nothing; a
792
- player despawned after asking has no body by the pass; a scene load or a
793
- dispose (`reset`) drops what was asked, so a door trip from a keyed scene
794
- to one without the key starts clean; the key going away means the next
795
- frame asks for nothing; a frame that never reached physics, or a force
796
- asked for after the pass (from a collision callback), is not used in a
797
- later frame (requests carry the scene time they were asked at). Code that
798
- places the player through its body (the hub's fall catch, the multiplayer
799
- kit's placement and clamps: `setTranslation` and a zero velocity, after
800
- physics) needs nothing new: there is no force to clear. A behavior that
801
- wants a steady push asks every frame from `update`, and stops by not
802
- asking. scripts/test-steady-hover.mjs holds all of it, on a stand-in
803
- rapier and, where rapier is installed, on rapier itself.
804
- - `"engine": { "view": { "far": 80, "fogFrom": 60, "fogColor": "#bfe3f2" } }`
805
- limits the world camera's view distance independently of the camera keys.
806
- `far` is metres, a number in 20..1000; absent or invalid means the whole
807
- view key is ignored. Each keyed frame sets the camera's far plane and
808
- updates its projection only if it changed, and sets linear `THREE.Fog`
809
- ending at `far`. `fogFrom` is optional (default `0.75 * far`); finite
810
- numbers clamp to 0..just below far, other values use the default.
811
- `fogColor` must be `#rrggbb`. Otherwise fog follows the visible kit sky:
812
- the texture row nearest the horizon, averaged across bearings, or the
813
- zone's flat colour if its texture cannot be read, blended as the sky fades
814
- between zones. Without a kit sky it uses a colour Three scene background,
815
- then a `#rrggbb` scene-data `background`, or neutral `#808080`. Horizon
816
- sampling happens once per art entry and only under this key. The kit sky
817
- ignores fog and its vertex shader places it
818
- on the far plane, so reducing the view distance never cuts it off.
819
-
820
- Lifecycle is the orbit lens's: remember the original far and exact fog
821
- object on the first keyed frame; give both back on physics reset/load,
822
- an editor frame (no runtime), and world disposal. Keyed after keyed takes
823
- them anew. A world that never meets a valid key has no record, allocates
824
- nothing, and writes no camera or fog properties (engine3d/viewrange.js;
825
- scripts/test-view-range.mjs, run by check).
826
-
827
- Materials: kit physical/standard materials and basic outline hulls keep
828
- Three's fog chunks. The rim/AO, glow, vertex-finish and near-shadow fade
829
- hooks preserve them; nearshadows itself only changes the shadow pass.
830
- The sole custom ShaderMaterial is the sky, intentionally `fog: false`.
831
- No world surface needs a shader change. Deck-supplied shaders must handle
832
- fog themselves. Turning fog on selects fog-enabled shader programs once;
833
- expect a one-off compile stall of tens to hundreds of milliseconds on a
834
- phone with several variants (an estimate, not a device measurement).
835
- Changing fog distances or colours does not recompile those programs.
836
-
837
- - `"engine": { "camera": { "follow": "rigid", "control": "orbit" } }` (the
838
- same `camera` object) asks the `Player` behavior for a third-person camera
839
- the player controls: they turn it, tilt it and zoom it, walking is
840
- relative to it, and the character turns to face the way it walks. Without
841
- it the Player drives like a tank (A/D and a sideways drag steer, the
842
- camera stays behind) and the camera's height and distance are the fixed
843
- `camHeight` and `camDistance`. The terms:
844
- > With `control` absent, everything is exactly as before: the same code,
845
- > the same calls on `scene.physics3d` in the same order, the same camera,
846
- > the same listeners on the canvas, for a scene with no camera key and for
847
- > one with `"follow": "rigid"` alone. `control` means something only as
848
- > exactly `"orbit"` beside exactly `"follow": "rigid"`; anything else, or
849
- > `"orbit"` without the rigid follow, is as absent. The key is read when
850
- > the scene loads (`scene.cameraControl`, `'orbit'` or `null`), as the
851
- > other engine keys are. With the key present the Player hovers, jumps and
852
- > falls as it does under `"follow": "rigid"` (forces), and the camera
853
- > moves with the player as that one does: the player's ground position is
854
- > not eased, its height is.
855
-
856
- Controls under the key:
857
- - Touch and pen: a drag that starts in the left half of the canvas is the
858
- movement stick (the same stick, `scene.moveInput`: 56 px to full
859
- deflection, analogue). A drag that starts in the right half turns and
860
- tilts the camera, 0.006 rad per CSS pixel: dragging right swings the
861
- view right, dragging up looks up (the camera goes lower). The left half
862
- is the stick's: a finger that lands there is never part of a pinch, so
863
- a thumb put down to walk while the other looks walks, and two thumbs
864
- put down together walk and look. Two fingers that both landed in the
865
- right half (the second while the first is still a tap or turning the
866
- camera) are a pinch: fingers apart bring the camera nearer; while they
867
- pinch neither turns the camera, a finger in the left half can still
868
- take the stick, and the finger left when one lifts does nothing more
869
- until it lifts too. A second drag in the left half while the stick is
870
- held does nothing. A short tap that did not move still jumps, anywhere;
871
- a finger that was part of a pinch, or left spent, never jumps.
872
- - Mouse: a drag with any button turns and tilts, and is never the stick;
873
- the wheel zooms, a tenth per notch; the context menu is kept off the
874
- canvas. A left click that did not move jumps.
875
- On a desktop a drag holds the pointer lock (Roblox's right-drag), so
876
- the cursor hides and stays put while turning. A right press asks for
877
- it at once. A left or middle drag asks once it passes the tap slop, or
878
- when a second button is pressed while it is still a tap, so a click
879
- never locks. While locked the turn comes from movementX/Y at the same
880
- `LOOK_RAD_PER_PX`. The lock ends with the drag: the last button up, a
881
- pointermove with no button down, the window's blur, the page hidden,
882
- a scene load, or detach. Per the Pointer Lock spec the browser puts
883
- the cursor back where the lock began. When the browser ends it
884
- (Escape, or the host page taking focus), the drag ends with no tap. A
885
- lock of ours that lands after the release, while the next press is
886
- still a tap, or after a scene load, is let go of as soon as it is
887
- known. A lock that lands takes the capture of every pointer down on
888
- the canvas (the spec's implicit release), and no capture can be taken
889
- while it is on. So every pointer down on the canvas gets its capture
890
- back when a lock of ours ends, however it ends: under the key or
891
- without it, mouse or touch, including a touch put down during the lock.
892
- The captures are given back when our unlock's pointerlockchange
893
- arrives, not when pointerLockElement clears. Chromium clears it inside
894
- exitPointerLock and sends the event later. While a request of ours is
895
- out, the lock is ours, or that event has not arrived, the document
896
- listens (capture phase) for pointerup and pointercancel. A held
897
- pointer lifted beyond the canvas in that window has its own event
898
- handed to its own handler (Scene3DPlayer's pointerup handler, keyless
899
- or not), so the stick stops and a tap still jumps, as origin/main's
900
- capture would have done. A pointer whose lift was never seen and that
901
- cannot be captured again is let go of as a pointercancel would be.
902
- Scene3DPlayer's keyless handlers report their pointers to the orbit
903
- input (`orbit?.pointer(event)`) in a runtime that has met the key; one
904
- that never met it has no orbit input, and nothing changes. A lost pointerup never leaves a mouse pointer held: the next
905
- press, a move with no button down, or a blur ends it. If
906
- requestPointerLock is missing (iOS), throws, rejects (Chrome refuses a
907
- re-lock about 1 s after Escape) or fires pointerlockerror, that drag
908
- goes on unlocked on the pointer capture taken at the press, as before
909
- the lock, and the next drag asks again. A drag request that returns a
910
- promise is followed by the promise alone, and a pointerlockerror is
911
- never taken for ours then. Old Safari returns no promise, so there an
912
- error might be another element's, and our request stays watched for
913
- 1 s after one. Touch and pen never lock. Listeners: blur and
914
- visibilitychange while a mouse button is down under the key;
915
- pointerlockchange while a drag has asked or our exit's event has not
916
- come (a scene load between or not, so the captures can be given back);
917
- the document's pointerup and pointercancel while a request is out, the
918
- lock is ours, or that event has not come; and pointerlockchange and pointerlockerror while an
919
- event-only request is out. A scene load with a request out leaves
920
- only the document's pointerup and pointercancel listeners when the
921
- request returns a promise, plus the request's own two when it does
922
- not, until it is answered and any lock it brings has been let go of. Nothing at all without the key (engine3d/orbitinput.js
923
- `makeMouseLock`;
924
- scripts/test-camera-orbit.mjs `mouseLock`). castle.xyz's DeckPlayer
925
- iframe is sandboxed with `allow-pointer-lock`.
926
- On a desktop (`(hover: hover) and (pointer: fine)`, with pointer lock
927
- supported), Shift or the small lock button at the bottom right toggles
928
- shift lock. It starts off and is never saved. A repeated Shift keydown,
929
- or one in an editable field, does not toggle; Shift still reaches
930
- `scene.keys`. The button is made lazily beside the canvas under the
931
- orbit key only, hidden on every scene load until a keyed scene plays
932
- again, and removed on detach. Clicking it gives focus back to the canvas.
933
- The mode is on only once the pointer lock lands; a refused or missing
934
- lock leaves it off. While on, every mouse move turns and tilts from
935
- movementX/Y at `LOOK_RAD_PER_PX`, with no button needed. A quick left
936
- click still jumps, presses never start a look-drag or take or release
937
- the lock, and the wheel still zooms. Shift again, Escape or any browser
938
- unlock, blur, the page hidden, every scene load, and detach end it,
939
- with no look or stick left held. Held pointers get their captures back
940
- through the same lock-end path as a drag. Touch and pen keep their
941
- controls, and touch-only devices get no button. Nothing is made in a
942
- runtime that never meets the orbit key. This changes only input: no
943
- character facing or camera offset (scripts/test-orbit-shift-lock.mjs).
944
- - Keys: W/S and up/down walk away from and toward the camera, A/D
945
- strafe, left/right swing the camera, Space jumps.
946
-
947
- What the Player's properties mean under it: `speed` and `jumpSpeed` are
948
- what they were. `turnSpeed` is how fast left/right swing the camera,
949
- rad/s; the character itself turns to face its walk at a fixed 12/s.
950
- The character faces the way it walks; standing still it keeps its
951
- facing. It starts facing away from the camera (PI - camAngle, as without
952
- the key). Without the key its facing is always PI - camAngle, so code
953
- that turns it sets camAngle; under the key the camera and the character
954
- turn apart, and turning the character is asked for: `scene.faceRequest =
955
- <radians>`, taken once by the Player's next update (a value that is not
956
- a finite number is dropped) and dropped by a scene load. The hub asks
957
- this way beside each of its camAngle writes (its arrival facing, a jump
958
- to a door); any other deck that turns the player must do the same, since
959
- a camAngle written without a request turns only the camera. The
960
- player's own left/right and drags turn the camera only.
961
- The camera is Roblox's default (Classic) third-person camera at our
962
- scale. A Roblox character is 5 studs tall; the kit's avatar
963
- (player.pxmodel on its 1.4 m capsule, the hub's) is 1.46 m from its soles
964
- to the top of its cap, so one stud is 0.292 m (`STUD`), and every Roblox
965
- distance below is that many studs:
966
-
967
- | | Roblox | here |
968
- | --- | --- | --- |
969
- | 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 |
970
- | 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 |
971
- | 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`) |
972
- | 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 |
973
- | tilt | 80 degrees either way | 80 degrees above to 80 below the horizontal (`ORBIT_PITCH_MOST`, `ORBIT_PITCH_LEAST`) |
974
- | field of view | 70 degrees, vertical | 70 degrees, or the scene's `engine.camera.fov` (below) |
975
- | occlusion (Popper) | snaps in front of what is in the way, eases back out | the same (Collision, below) |
976
-
977
- `engine.camera.distance` and `engine.camera.pitch` are optional starting
978
- values only, read only under the orbit key. Each absent, non-finite or
979
- non-number value keeps its default exactly: 3.65 m or 15 degrees down.
980
- They do not limit the player's zoom or tilt: the full limits above still
981
- apply. `camDistance` and `camHeight` do not move the orbit camera. A
982
- change to either of them or either starting key (a deck edit or a scene
983
- with different values) reapplies both starting values; unchanged values
984
- keep what the player chose throughout play. It looks at the player
985
- 0.438 m above its Transform (the fixed cameras look 0.5 m above). Below
986
- the horizontal the camera is lower than the point it looks at, looking
987
- up, and the ground holds it above itself as a wall holds it in front
988
- (Collision); a scene with `"ground": { "none": true }` has no drawn
989
- ground to go under, and its floors are fixed solids that hold it alike.
990
-
991
- Moment shots. Deck client code can set the player's runtime scene
992
- (the `scene` passed to `Player`) to
993
- `scene.orbitShot = { look: { x, y, z }, distance, pitch, yaw }`.
994
- Distance is metres, greater than zero; pitch and yaw are degrees in the
995
- orbit's sense (positive pitch puts the camera above the look point,
996
- looking down). Pitches past 89 degrees in either direction are drawn at
997
- 89 degrees in that direction; the blend also stays within those limits
998
- to retain the view's azimuth. Its position is `look + distance * direction`,
999
- where
1000
- `direction = { x: -cos(pitch)*sin(yaw), y: sin(pitch), z: cos(pitch)*cos(yaw) }`
1001
- with the angles converted to radians. Position and look point ease from
1002
- the drawn view at 10/s (`TAKEOVER_RATE`), then hold until changed or
1003
- cleared. The position eases in yaw (shortest arc), pitch and distance
1004
- around the drawn look point, so opposing shots swing round it. A settled
1005
- shot holds its exact pose. A changed shot eases from the current view;
1006
- an equal assignment continues it. After another system moves or turns
1007
- the camera or a frame without placement, a shot starts from its current
1008
- direction; an interrupted hand-back drops its look offset and looks at
1009
- the player.
1010
- The lens stays the orbit lens. The shot is drawn as given,
1011
- without collision: the deck author must place it clear of solids.
1012
- Clearing with `undefined` or `null`, or supplying an invalid shot
1013
- (missing look, non-finite numbers, distance <= 0), gives back the player's
1014
- chosen orbit through its usual takeover blend and collision handling;
1015
- the look point's offset from the player decays at 10/s, without a rotation
1016
- snap or trailing a walking player. Below 0.1 mm it returns to the exact
1017
- player look; a teleport clears the offset at once.
1018
- Look input is consumed and dropped during a shot; walking is
1019
- untouched. The player's camAngle, zoom and tilt are kept. Shot state
1020
- lives on actor.runtime, per player; without the orbit key it is never
1021
- read, and a scene that never sets it keeps its camera and movement.
1022
- Checked by scripts/test-orbit-shot.mjs, also run by test-camera-orbit.mjs.
1023
-
1024
- The lens. The world camera is 50 degrees tall (`makeWorld3D`), and no
1025
- scene key changes it without the orbit key. Under the key it is
1026
- `engine.camera.fov` degrees (the same `camera` object: a number from 10
1027
- to 120; anything else, or none, is 70, Roblox's), read from the scene the
1028
- runtime loaded, set on the world camera with `updateProjectionMatrix` by
1029
- `renderWorld` on each keyed frame (engine3d/orbitlens.js). The lens the
1030
- camera had when the key first met it is kept (`world.orbitLens`) and
1031
- given back exactly, projection and all, when the keyed scene goes, before
1032
- any code of what follows runs: at every scene load (the physics system's
1033
- `reset`, which `load` runs before the new scene's data is in), on an
1034
- editor's frame and on `disposeWorld`. So a keyless scene after a keyed
1035
- one (a door to a keyless deck in the same world) starts from the lens the
1036
- camera had, and whatever field of view its own code sets stands, 70
1037
- included: no keyless frame looks at the camera. A keyed scene after a
1038
- keyed one takes the lens again on its first frame. A world that never
1039
- plays the key never touches the camera. The editors have their own worlds
1040
- and cameras. (Instanced copies are culled before `renderWorld`, with the
1041
- lens of the frame before: on a keyed scene's first frame they are culled
1042
- with 50 degrees.)
1043
-
1044
- Limits: the tilt stays between 80 degrees below and 80 above the
1045
- horizontal and the distance between 1.5 and 37.376 m. What is asked is
1046
- eased in at 20/s.
1047
-
1048
- Collision (Roblox's Popper, with a ball): each frame a ball of the
1049
- margin's radius (below) is swept from the point the camera is placed
1050
- from (the player, with its height eased as the camera eases it, 0.438 m
1051
- up) toward where the camera wants to be, as far as its distance, against
1052
- fixed bodies' solid colliders only (`scene.physics3d.castBallFixed(origin,
1053
- dir, maxToi, radius)`, rapier's `castShape` with a `Ball` and the filter
1054
- of `castRayFixed(origin, dir, maxToi)`: sensors and dynamic and kinematic
1055
- bodies are passed through, so other players and thrown things do not move
1056
- the camera). Where it first touches something (its time of impact) is a
1057
- limit on how far out along that line the camera may be. A ball that far
1058
- out is the margin off whatever stopped it and off everything it passed,
1059
- square to the surface, however the line meets it: a wall at a grazing
1060
- angle, a box's edge or corner, the ground seen along at a low angle, a
1061
- second wall in a corner. The margin is 0.25 m, or, for a wider lens, the
1062
- distance from the camera to the near plane's corners, near * sqrt(1 +
1063
- tan^2(fov/2) + (aspect * tan(fov/2))^2), plus 0.05 m, whichever is more
1064
- (`lensMargin`, from the scene's lens and the camera's near and aspect):
1065
- 0.25 m at 70 degrees on 20:9 (corners 0.198 m off), 0.484 m at 120
1066
- degrees on 20:9, 0.265 m at 120 on 9:20. So the whole near plane stays in
1067
- front of every surface at every lens from 10 to 120 degrees, any aspect,
1068
- every tilt and zoom. A nearer limit is taken at once; a farther one, or
1069
- none, is eased out to at 6/s, never past what this frame's ball touched,
1070
- and let go once the camera is back at its distance. The ease is measured
1071
- from the look point, from how far from it the camera was drawn last
1072
- frame, and turned into a distance along this frame's line from this
1073
- frame's start (`alongRay`): the start moves as the player nears or leaves
1074
- a wall, so last frame's limit along its own line is not where the camera
1075
- was (review 7: a wall 0.5 m off removed let the camera out 1.161 m in a
1076
- frame where easing at 6/s allows 1.139). It eases whatever drew the
1077
- camera short of its distance, a start moved off a wall as well as a ball
1078
- that held it (review 8: a box beside the look point removed let the camera
1079
- out 0.062 m where 0.006 m is allowed); only the player's zoom moves it at
1080
- the zoom's own pace (a zoom in past where it is held takes it in at once).
1081
- The ball is swept only as far as the camera will be drawn this frame, so
1082
- the place drawn is the place whose end the sweep checks. The camera is drawn at the nearer of its eased distance and the
1083
- limit, so zooming in while held in front of a wall brings it no nearer
1084
- until the distance asked is nearer than the wall, the view is never
1085
- inside a wall and never pops outward, and an easing camera never passes
1086
- something the ball touches (review 5: the axis-ray push and line pull-in
1087
- of reviews 3 and 4 left a camera 8 mm off a box at a grazing angle, and a
1088
- pull-in made for one frame alone let the eased limit run on, so the
1089
- camera jumped 3.985 m out in a frame when it stopped).
1090
-
1091
- Rapier's answer for a swept ball is off by an amount that changes from
1092
- place to place (short by centimetres against the ground and tens of
1093
- centimetres along a wall met at a grazing angle; past the surface by up
1094
- to 2 cm, or missing it, when the ball starts within a few centimetres of
1095
- one; in a corner it can name the second solid instead of the first), so
1096
- `castBallFixed` puts the ball where it touches the plane that touches the
1097
- solid where it was met (exact on a face; a convex solid is all behind it
1098
- at an edge or a corner) and checks that place with an overlap query, the
1099
- ball 0.05 mm smaller; another solid in the way there is swept against
1100
- alone and the ball put where it touches that one, three times at most.
1101
- Rapier can also miss a solid outright (review 8: a box the ball passes
1102
- through, at one radius and not a millimetre more), so its answer is only
1103
- where to look: with no hit the ball's end (the place the camera will be
1104
- drawn) is checked all the same, a ray along the line keeps the line of
1105
- sight, and a place still not clear is found by halving between the start
1106
- (clear) and it with overlap queries, to 1 mm in 16 halvings at most.
1107
- `castBallFixed` is three rapier queries as a rule (sweep, ray, overlap)
1108
- and 25 at most. Rapier does not answer a ball that
1109
- starts touching something either, so the ball starts clear: every fixed
1110
- surface within the margin and 0.05 m of the start
1111
- (`scene.physics3d.nearFixed(point, within)`, each solid's nearest point and
1112
- normal) gives a plane touching its solid there (a convex solid all behind
1113
- it), and the start is the look point moved the least way that puts it
1114
- that far in front of every plane found so far, all together (the nearest
1115
- point of the half-spaces' intersection), then looked around again, eight
1116
- times at most. Together, a corner's walls do not undo each other's moves
1117
- (review 6: one wall at a time, a 60 degree corner left the camera 8.66 mm
1118
- off a wall with the near plane through it). The move grows from nothing as
1119
- the player comes nearer, so the camera does not jump. Where no place near
1120
- the look point is that far off every plane (a gap narrower than twice the
1121
- margin) the place that falls least short is taken and the ball made that
1122
- much smaller (in a gap 0.7 m wide, its middle, the camera 0.3 m off both
1123
- walls), no smaller than 0.02 m. There the lens cuts into the walls: the
1124
- camera point stays out of them, but no place keeps the near plane out
1125
- (at 120 degrees on 20:9 its corners are 0.434 m from the camera), so the
1126
- view shows the inside of a wall at its edges. This is accepted, as
1127
- 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
1128
- camera had before the ball (`onRay`, with `castRayFixedNormal`, which is
1129
- `castRayFixed` with the surface's normal): a margin short of the hit, no
1130
- nearer the look point than 0.6 m, never past a real surface (then 0.01 m
1131
- short of it). `castRayFixed` itself is what it was: `{ distance, actorId }`.
1132
- While a takeover blend lasts (below) the point actually drawn, its place
1133
- plus what is left of the blend, is swept toward the same way: pulled in
1134
- along its own line to where the ball stopped, and the pull is kept in the
1135
- blend, so the next frame eases on from there. Once a wall has held a
1136
- blend in, it is let out at the collision pace for the rest of that blend:
1137
- no farther from the look point than easing at 6/s from where it was drawn
1138
- toward where the camera rests this frame (review 9: a wall removed under a
1139
- held blend let its 10/s carry the camera 0.246 m out in a frame where
1140
- 0.179 m is allowed), and let go within 0.1 mm of it. Where it rests, not
1141
- its distance: a start moved off a wall can put the camera farther out
1142
- than its distance, and easing toward the distance held such a blend open
1143
- for good (review 10: 0.093 m short after 20 s, a sweep more every frame).
1144
- A blend no wall has held keeps its own pace. Tests
1145
- (scripts/test-camera-orbit.mjs): `grounded` on a stand-in plane and on
1146
- rapier's own ground, `wideLens` on a stand-in wall, `grazing` on rapier
1147
- (the review 3 case at 120 degrees, 20:9, level, yaw -3, farthest zoom; a
1148
- sweep near grazing on 20:9 and 9:20 at 70 and 120 degrees, a player 0.8 m
1149
- from the wall and against it; a corner of two walls over the ground;
1150
- review 4's post, 240 settled frames whose line to the player meets
1151
- nothing and that do not move), `popClear` and `popSteady` (review 5 on
1152
- rapier: two boxes beside the line and a blocker removed; every frame
1153
- after, the camera is the margin off each box and the ground, measured on
1154
- the boxes, and moves out no faster than easing at 6/s allows), `corners`
1155
- (review 6 on rapier: the player pressed into corners of 30 to 150
1156
- degrees, two square walls under a ceiling and a 60 degree corner under
1157
- one, the camera turned every way: every frame the margin off every solid,
1158
- less 0.1 mm, and no near-plane corner inside one), `narrowGapStable`
1159
- (walls 0.7 m apart: only that the camera point is never inside a wall,
1160
- nothing is NaN and a settled camera stays put; the lens does cut the
1161
- walls there) and `releaseEase` (review 7: walls 0.36 to 0.6 m off at four
1162
- angles, removed; no frame moves the camera out from the look point
1163
- faster than easing at 6/s allows).
1164
- Also `releaseBeside` (review 8: a box beside the look point removed, eased
1165
- out at 6/s), `randomBoxes` (review 8: 120 seeded cases of one or two
1166
- boxes turned any way, mostly in the camera's way, 70 and 120 degrees on
1167
- 16:9 and 20:9; every frame the camera the margin off each box less 1 mm
1168
- and no point of a 21 x 21 near-plane grid inside one; the review's case
1169
- is the first), `ballMisses` (rapier's sweep made to miss: the ball
1170
- still stops its radius off the wall) and `blendRelease` (review 9: blends
1171
- handed back from three places, a wall at two distances removed or kept,
1172
- no wall, and (review 10) a wall and a corner 0.4 m off at 70 and 120
1173
- degrees: eased out at 6/s once released, every blend ends and is no
1174
- longer held, one sweep a frame after, the camera stays, and with no wall
1175
- it is about there in 0.3 s). Queries a frame: one `nearFixed` in
1176
- the open, two by a wall or in a corner (eight at most), and one sweep, one
1177
- more while a takeover blend lasts; a sweep is three rapier queries as a
1178
- rule and 25 at most. As a rule 4 in the open and 5 by a wall; the worst
1179
- case is 8 + 2 * 25 = 58 (a blend, a slanted corner, and rapier missing
1180
- solids in both sweeps); none on a
1181
- frame physics has no world. Popped in near the player the camera
1182
- is within an avatar's own hiding distance, as Roblox's goes through its
1183
- character when pressed close, and the model is hidden (below).
1184
- A frame whose final camera (after anything else placed it) is within
1185
- 1 m of the player's own model (in world space, the segment from its
1186
- 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
1187
- the view is not the inside of the avatar (engine3d/ownmodel.js). The
1188
- Player names its actor for the frame's draw (`scene.orbitOwnModel`, set
1189
- by each placement, taken by the draw, dropped by `reset`), and the play
1190
- loop sets that node's `visible` to false for the one render (only a node
1191
- that was shown), inside try/finally, and back to true after it if it is
1192
- still false; nothing else is put on the node, so a deck's own hide, a
1193
- rebuilt node and a Player turned off or removed need nothing. Positions
1194
- are measured as WebGLRenderer.render will draw them (`world.scene`
1195
- updated when its `matrixWorldAutoUpdate` is on, cached when off; a
1196
- parentless camera by its own flag), writing no matrix; a node not under
1197
- `world.scene` is not hidden. A `false` a deck writes from inside the
1198
- render of a hidden frame is shown again after it. Accepted: anything
1199
- that copies the node from inside that render (clone, copy, toJSON, its
1200
- own or a parent's) copies `visible: false`, as for any node a deck hides
1201
- for a frame; three.js treats `visible` as plain state. Also accepted: the
1202
- decision is made before the render, so a camera a deck moves from
1203
- `scene.onBeforeRender` (which three.js calls after the matrices, before
1204
- the render list) is judged where it was before that callback; under the
1205
- key the Player places the camera, and catching that callback would mean
1206
- putting something on the scene. Only the
1207
- local player is hidden; nothing is sent. While hidden it casts no
1208
- shadow; a model drawn as shared instances (`instanceModels`) is not
1209
- hidden. Without the key the field is never set and the loop calls
1210
- `renderWorld` as before.
1211
-
1212
- `scene.three.ownModelWith` is a `Set<Object3D>` for extras that should hide
1213
- with the own model, such as multiplayer-3d's own name-tag sprite. Add an
1214
- object while it belongs to the player and delete it when disposed or
1215
- replaced. The set is read only in a render that actually hides the model;
1216
- keyless frames never read it. Only shown, writable objects under
1217
- `world.scene` are hidden, with the same try/finally visibility contract as
1218
- the model; anything other than a Set there is ignored. Detaching or unregistering one during the render still restores
1219
- it if its visibility is still false; an already hidden object is left alone.
1220
-
1221
- There is no return-behind (no swinging the camera back behind a walking
1222
- player when it is left alone): walking forward already keeps the camera
1223
- behind, and chasing a strafe would turn a straight walk into a circle.
1224
-
1225
- Where the state is. The yaw is `scene.persistent.camAngle`, with the
1226
- meaning it always had (the camera sits at player + (-d sin, h, d cos) of
1227
- it), so code that reads or sets it (the hub's arrival facing) works as
1228
- before; a yaw set a full turn away is reached the short way round. The
1229
- tilt and distance the player chose are client-only: they are on the
1230
- runtime (`scene.cameraOrbit`), which a scene load does not replace, so
1231
- they carry from scene to scene (a Player with other
1232
- `camDistance`/`camHeight` starts from its own), and are never on
1233
- `scene.persistent`, which the multiplayer kit sends. What the camera is
1234
- doing between frames is on the actor's `runtime`, which a scene load
1235
- rebuilds. `scene.lookInput` (engine3d/orbitinput.js) holds what the
1236
- pointers asked for until the Player takes it, once a frame; it is made
1237
- the first time a pointer goes down under the key or a Player runs under
1238
- it (`scene.orbitInput()`), so a runtime that never meets the key has
1239
- none.
1240
-
1241
- When something else has the camera. A teleport (more than 3 m in a
1242
- frame) snaps it, and so does a camera more than 20 m from its place. The
1243
- camera is the player's to steer on a frame only when the Player also
1244
- placed it on the frame before (so a Player turned off, even for a frame
1245
- and even by a collision callback after its update, does not come back to
1246
- a queued drag), the camera is where the Player left it, and the look
1247
- input is not locked. `scene.lookInput.lock()` makes the next take empty
1248
- and drops what was asked; the hub calls it each frame of a door trip
1249
- under the key (beside its `lockInput`), so a drag made during a
1250
- trip neither moves the trip's camera nor turns the view when it ends. On
1251
- any frame the camera is not where the Player left it (a hub trip writes
1252
- it every frame; the first frame of a scene; a Player turned off and on)
1253
- the Player starts again from the chosen tilt and distance and eases on
1254
- from where the camera was put (a twentieth of the way left after 0.3 s).
1255
-
1256
- Loads. A scene without the key, loaded after one with it, runs the code
1257
- it always ran from its first frame: the latch is per load, and the
1258
- Player's and the input's branches each read it once. On every scene
1259
- load and on dispose the physics system's `reset` resets the orbit input
1260
- (`scene.lookInput.reset()`, only when it is the one orbitinput.js made:
1261
- `isOrbitLook`): every pointer it holds is let go of (the stick released
1262
- if one of them held it, no tap), what was asked of the camera is
1263
- dropped, and the wheel and context-menu listeners are taken off; a keyed
1264
- scene's Player puts the listeners back on its first frame. A
1265
- `faceRequest` not yet taken is dropped on every load, whether or not the
1266
- orbit input was ever made. A tap already taken as a jump and not yet
1267
- used carries across a load with or without the key, as it always has. A
1268
- runtime that never met the key has no orbit input.
1269
- So a finger held across any load into or out of a keyed scene, or
1270
- between two keyed scenes, does nothing more until it lifts: the old
1271
- handlers do not know it either. A finger the old handlers hold across a
1272
- load into a keyed scene keeps their stick until it lifts or a pointer
1273
- goes down under the key, which lets go of everything they hold; only
1274
- one of the two ever writes the stick. scripts/test-camera-orbit.mjs
1275
- holds all of it, with the Player as it was before the key
1276
- (scripts/Player.before-orbit.mjs) and Scene3DPlayer's `attachInput` as
1277
- it was (scripts/Scene3DPlayer.before-orbit.jsx) as the references for
1278
- the scenes without it, and the loads, the lock and a Player turned off
1279
- and on run through physics-2d's SceneRuntime and Scene3DPlayer's own
1280
- `attachInput`.
1281
- - `"engine": { "look": { "bake": "deferred" } }` at the scene file's top
1282
- level (the same `engine` object) asks the engine to draw the scene's models
1283
- before their look is baked. Building a model bakes two things into it
1284
- (`engine3d/look.js`): its soft shading, by casting rays from every vertex
1285
- through a grid of the model's surfaces, and the attributes its outline is
1286
- pushed out by. That is most of what a model costs to build, and all of it
1287
- happens before the first frame: on a slow phone, several seconds of a
1288
- town's load. With the key a model is drawn at once without them, and they
1289
- are baked a little after each frame, nearest the camera first, about 6 ms a
1290
- frame. What a player sees: the scene appears sooner, flat-shaded where
1291
- parts meet and with no outlines, and over the first seconds the shading
1292
- and the outlines come in, model by model. The terms:
1293
- > With the key absent, a model is built exactly as before: the same code,
1294
- > baked before `syncActors` returns. With the key present, a model is built
1295
- > in the same shape, with the same meshes, materials and shader programs
1296
- > (nothing is recompiled when the baking lands), its occlusion all 1
1297
- > (nothing occludes it) and its outline hulls there and not drawn (their
1298
- > material's `visible` is off); once its baking has run, every attribute of
1299
- > every geometry holds what baking at once would have put there, and the
1300
- > hulls are drawn.
1301
-
1302
- Any other value of `bake`, or none, is the key absent. It is read when the
1303
- scene loads (`runtime.bakesLookLater`), so it follows a scene switch, and
1304
- it applies to models `syncActors` builds while that scene plays, in the
1305
- play panel, a published deck and the scene editor alike; the model editor
1306
- and thumbnails build their own and always bake at once. A model already
1307
- baked (built for a scene without the key, or one whose baking has run) is
1308
- never unbaked. The other way round, a model built under the key and still
1309
- waiting when a scene without it places the same model in the same world is
1310
- the same shared build: it is drawn unbaked there too until its baking has
1311
- run, which goes on whichever scene plays. Whether a pass bakes later is
1312
- written on the world when `syncActors` starts (`world.bakesLookLater`), so
1313
- a `syncActors` for another runtime entered from inside a pass leaves its
1314
- own answer there for the rest of the outer one: models the outer pass
1315
- builds after it are baked as the inner runtime's scene asked. They end
1316
- the same either way.
1317
-
1318
- It goes with `"dropEmptyParts": true`: that key takes the empty groups out
1319
- of a shared build after its look was applied and its baking queued, and the
1320
- baking was written down as geometries and matrices, so with both keys a
1321
- scene ends as it does with `dropEmptyParts` alone.
1322
-
1323
- How it goes (`engine3d/lookbake.js` has the queue, the end of `look.js`
1324
- what is queued): one task per model built, cut into steps (the grid, each
1325
- surface marked into it, the rays of 128 vertices, a stretch of 384
1326
- vertices or triangle corners of a geometry's outline attributes, part by
1327
- part for merged parts). After each frame is drawn
1328
- (`renderWorld`), steps are started until 6 ms have gone; a step is never
1329
- interrupted, so a long one overruns and nothing starts after it that frame.
1330
- The frame the queue is first seen bakes nothing, so the first frame is on
1331
- screen first. Tasks are put nearest first whenever the queue has grown, by
1332
- the distance from the camera to the nearest actor placing the model as
1333
- things stood then; they are not re-sorted as the player walks. A task
1334
- bakes from what was written down when the model was built (each surface's
1335
- geometry and where it stood), so a model moved or animated since bakes the
1336
- same. Models sharing a parsed model file share one bake, as before, and a
1337
- geometry is baked once however many copies draw it.
1338
-
1339
- `scene.three.lookBake` is null in a world that never built a model under
1340
- the key; otherwise it is the queue: `shown` (true once a frame has been
1341
- drawn with nothing left to bake, false again from the moment a model is
1342
- queued), `pending` (models still to bake), `ms` (time spent baking),
1343
- `baked` and `dropped` (tasks that ran to the end and left the whole of the
1344
- baking in every geometry not disposed, and tasks that did not: the model
1345
- went first, or a geometry was left that could not be written to), and
1346
- `budgetMs`, which a deck may set. **A harness, a screenshot or
1347
- a cover waits for `lookBake === null || lookBake.shown`, not for `pending`
1348
- to reach 0**: the baking is done after the frame is drawn, so the frame
1349
- that brings `pending` to 0 was drawn without the last of it, and it is the
1350
- next one that is the complete picture. A model released, rebuilt (its
1351
- file, its art or the look switch changed) or disposed with its world before
1352
- its task ran is dropped: the task listens for its geometries' `dispose` and
1353
- never writes to one that has been disposed.
1354
-
1355
- A geometry replaced while it waits: a copy made with `geometry.clone()`
1356
- waits with the geometry it was copied from, and is given the same occlusion
1357
- and outline attributes when the task runs (in arrays of its own, as a copy
1358
- of a baked geometry has), so a mesh and its outline hull given the copy,
1359
- the first geometry disposed, end as they would in a scene without the key.
1360
- That holds whenever the copy is made (before the task begins or part way
1361
- through it) and whatever it is made from (the geometry, a copy, or either
1362
- one disposed and never written): a task counted in `baked` left every
1363
- geometry of its model that is not disposed, copies included, fully baked.
1364
- The engine does this itself for a part that glows. While it waits a
1365
- geometry has a `clone` of its own for this; it goes when the task ends, and
1366
- a `clone` kept hold of and called afterwards is the ordinary one.
1367
- Anything else put in a waiting geometry's place (a geometry built
1368
- separately, `copy()` into another one, or a copy whose vertices were then
1369
- replaced by a different number) is not written to: it keeps the occlusion
1370
- it came with, and an outline hull drawn from it has no outline attributes.
1371
- A task that ends with such a copy not disposed counts in `dropped`.
1372
- When the waiting geometry and every copy of it are gone before the task
1373
- runs, the hull's material is left not `visible`, so that hull has no
1374
- outline rather than a wrong one; a deck that swaps in its own geometry
1375
- under the key bakes it itself (`addOutlineAttributes`, engine3d/look.js)
1376
- and shows the hull. And a waiting geometry disposed while a mesh still
1377
- draws it is never baked, where without the key it would already have been.
1378
-
1379
- `scripts/test-look-bake.mjs` holds all of it, and holds what a build
1380
- without the key gives to a number (`BAKED_AT_ONCE`, a digest from
1381
- `scripts/look-baseline.mjs` of every kit model built at once): change it
1382
- only in a commit that means to change what the look bakes into a model.
1383
-
1384
- Do not set it if deck code reads `lookOcclusion`, `lookOutlineNormal` or
1385
- `lookOutlineReach`, or sets `visible` on an outline hull's material, in the
1386
- first seconds of a scene; and a screenshot or cover taken before
1387
- `lookBake.shown` is true shows the unbaked picture. Opt in when a
1388
- scene is many models and the load on a slow phone matters more than the
1389
- first seconds' polish; a small scene gains nothing.
1390
- - `"engine": { "sky": { ... } }` at the scene file's top level (the same
1391
- `engine` object) asks the engine to draw a sky behind everything: the sky of
1392
- the zone the player stands in, turning into the next zone's when they walk
1393
- into it. Without it the engine clears to black, and a camera that looks
1394
- above the horizon looks into black.
1395
-
1396
- ```jsonc
1397
- "sky": {
1398
- "fade": 1.5, // optional: seconds one zone's sky takes to turn into another's (above 0, at most 10)
1399
- "edge": 0.75, // optional: metres past a zone's box a player is still in it (0 to 10)
1400
- "below": 8, // optional: degrees under the horizon an image's last row is (0 to 45)
1401
- "zones": [ // 1 to 16; exactly one has no box
1402
- { "id": "square", "color": "#bfe3f2", "art": "drawings/sky-square.webp" },
1403
- { "id": "hollow", "color": "#3d3a5c", "art": "drawings/sky-hollow.webp", "box": [-95, -17, -17, 17] }
1404
- ]
1405
- }
1406
- ```
1407
-
1408
- The terms:
1409
- > With the key absent, a scene is drawn exactly as before: the same scene
1410
- > graph, the same render calls, the same clear to black; nothing of the
1411
- > sky's is made. With the key present, every pixel no opaque thing covers is
1412
- > the sky of one zone, or of two while one turns into the other, and
1413
- > everything else is drawn as it would be without the key: the sky is not
1414
- > lit, casts and takes no shadow, is not an actor, and is in the scene graph
1415
- > only while a frame of its scene is being drawn.
1416
-
1417
- A zone is `id`, `color` (`#rrggbb`), optionally `art` and optionally `box`
1418
- (`[x0, z0, x1, z1]`, metres). The zone with no box is the sky of a point in
1419
- no box; a point in two boxes is in the one listed first.
1420
-
1421
- **The shape is exact** (`physics-2d` `engine/skyKey.js` reads it at each
1422
- scene load). A key it does not name, a number out of range, a colour that is
1423
- not six hex digits, two zones with one id, no zone without a box or more
1424
- than one: the scene has no sky, the key reads as absent, and the console
1425
- gets one warning that says what was wrong. So a scene written for a later
1426
- engine that knows more keys has no sky on this one, rather than half of one.
1427
-
1428
- **A zone's picture** is a deck image (png, jpg, webp: `art` is its path in
1429
- the deck). It enters through the bundler like every deck image and is a
1430
- `data:` URI in a published deck; nothing is fetched. Across, it is the
1431
- bearing: north (-z) at the left edge, east (+x) a quarter of the way along,
1432
- its right edge meeting its left. Down, it is the height: straight overhead
1433
- in the first row, `below` degrees under the horizon in the last, and the
1434
- last row again below that. So the first row is one point of the sky and
1435
- should be one colour. It is drawn with linear filtering and no smaller
1436
- copies, as the whole sky whichever way the camera looks. A texture is made
1437
- when its zone is first drawn, and at most two are held (the zone drawn and
1438
- the one it is turning into). Where a zone has no `art`, or its image has not
1439
- arrived, failed, or is not an image (a `.sprite`), the sky is the zone's
1440
- `color`.
1441
-
1442
- **Which zone** is decided each frame from the local Player's Transform (the
1443
- first actor with a `Player` component), never the camera: a player is in a
1444
- box from its edge and stays in it until `edge` metres outside, so standing
1445
- on a line does not flicker. With no Player, the zone with no box.
1446
-
1447
- **The fade** takes `fade` seconds by the clock (a frame longer than a
1448
- quarter of a second counts as a quarter). A player who turns back mid-fade
1449
- sees it run backwards from where it is; one who walks on into a third zone
1450
- sees the fade under way finish, then the next. Nothing fades on a scene's
1451
- first frame, or when the player is somewhere else at once (more than 8 m
1452
- from where the frame before had them: a door, a put): the sky is simply
1453
- that zone's.
1454
-
1455
- **`scene.skyZone`** says it, to read: `{ id, blend, from, to }`. `id` is
1456
- the zone the player is in; the sky drawn is `from`'s turning into `to`'s,
1457
- `blend` of the way there, 0 to 1 (at rest `from` and `to` are both `id` and
1458
- `blend` is 0). It is the same object from one scene load to the next, kept
1459
- current as frames are drawn (it is one frame behind inside an `update`),
1460
- and it cannot be written. Before a frame is drawn, and after the scene's
1461
- world is disposed, it names the zone with no box. For a scene without the
1462
- key it is `null`, and nothing works it out. A system that fades something
1463
- else with the sky (a zone's sound) reads `from`, `to` and `blend`.
1464
-
1465
- What it costs: one draw call in the colour pass (none in the shadow pass),
1466
- under 500 triangles, one texture read for each pixel of sky (two during a
1467
- fade), and no overdraw: it is drawn after every opaque thing, on the far
1468
- plane, so only the pixels they left are shaded. A zone test and a few
1469
- uniforms each frame.
1470
-
1471
- How it stays out of the scene's way, and how long it lasts
1472
- (`engine3d/skylife.js` has the rule and all of the code that attaches,
1473
- detaches or disposes anything):
1474
- > The dome and its resources are attached, detached and disposed only by
1475
- > the outermost render of their world, or with no render of that world in
1476
- > progress. Nothing a callback does (re-enter, throw, load, dispose) can
1477
- > leave a dome in the scene graph, a disposed resource in a render list,
1478
- > or a sky record alive past its key.
1479
-
1480
- Every frame of a world with the key goes one way (`skyFrame`): counted in,
1481
- prepared, drawn, counted out, and, if it was the outermost, settled. The
1482
- settling alone enforces this, from what is true at that moment:
1483
- > After the outermost frame of a world returns or throws, EITHER
1484
- > `world.sky` is null, OR it is a record whose key is the key the frame's
1485
- > runtime has NOW for THIS world, with its dome out of the scene graph,
1486
- > and neither that frame nor any frame drawn from inside it threw.
1487
-
1488
- The key a runtime has for a world is its `sky`, unless the world is
1489
- disposed or the runtime draws in another world (its `three` is set and is
1490
- not this one): then it has none, and no sky is drawn for it there. A frame
1491
- from inside another, or from inside a disposal, never makes, steps,
1492
- attaches, detaches or disposes; a dome in the scene graph that is not of
1493
- its runtime's key is hidden for that draw. Errors are data: a step or a
1494
- disposal that throws does not stop the frame, which is drawn with no sky;
1495
- every release that is due still runs; the first error is thrown at the
1496
- frame's one exit, the frame's own over a kept one.
1497
-
1498
- Its mesh, material and textures are the mode's own, kept on `world.sky`,
1499
- one record for one load of one scene. The mesh is in the scene graph only
1500
- while a frame of that scene is being drawn, put there and taken out by
1501
- writing `parent` and `children` directly, so no three.js event is
1502
- dispatched and no listener of a deck's runs. So `skipUnchangedActors`,
1503
- `dropEmptyParts`, the look bake, a deck's own walk of `scene.three.scene`,
1504
- picking, and hub-game's Low tier never meet it; the orbit camera's reach is
1505
- physics, where it has no collider.
1506
-
1507
- What ends a record: the scene loaded again or another loaded
1508
- (`SceneRuntime.load`, through the physics system's `reset`; a load ends
1509
- only the record of the key it replaces), a frame of another scene or of
1510
- one without the key, an editor's frame (the editors give `renderWorld` no
1511
- runtime, and draw no sky), `disposeWorld`, the runtime pointed at another
1512
- world, and any frame that throws, or has a frame inside it throw, whether
1513
- or not what called that catches the error. It is disposed at once when no
1514
- frame of the world is being drawn, and otherwise by the outermost frame as
1515
- it settles. Every resource is disposed once, each in a guard of its own; a
1516
- disposal counts as a frame in progress, so a frame drawn from inside a
1517
- `dispose` listener is a frame from inside: it has no sky and makes
1518
- nothing. The next frame of a keyed scene starts from nothing, with no
1519
- fade. Two worlds keep their own.
1520
- `leaveSky` returns `null` only on success. World disposal and physics reset
1521
- propagate its first error with `failed !== null`, so a listener's `throw 0`
1522
- is preserved too. A failed reset stops the load before the new scene is
1523
- installed, after the sky's resources have been released.
1524
-
1525
- When `staticActors` is on too, every record release and each nonempty
1526
- shed-texture disposal runs through the world's `outsideCall` hook. The
1527
- entire disposal block is counted, so every texture, geometry and material
1528
- listener sees no recorded adoption and no frozen node, and a listener's
1529
- nested sync cannot adopt between resources or listeners. The callback is
1530
- made once per world, lazily when a record is actually made, and reused on
1531
- later records; unchanged frames do not test or call it. With no hook the
1532
- same block runs directly. This bracket changes neither the sky's ordering
1533
- nor its depth count or handling of errors: each listener still runs in its
1534
- own guard, the first error stays data, and it is thrown at the frame's one
1535
- exit after settling. The next actor pass is ordinary; later passes may
1536
- settle, unless the world was disposed.
1537
-
1538
- `runtime.sprites` and its entries are engine-made art data, the same records
1539
- the engine's other drawing reads. The sky reads the slot and `kind`,
1540
- `ready`, `failed` and `image` only with `Object.getOwnPropertyDescriptor`,
1541
- and uses only a data property's `value`:
1542
- > the sky reads art records only through own data properties, so a getter never runs
1543
-
1544
- An accessor slot or field, or an entry that is not a plain object (an
1545
- ordinary object or one with a null prototype), is not usable: the zone
1546
- shows its flat colour, with one warning naming the zone and art path per
1547
- world, including across sky record recreation. These reads run without
1548
- `outsideCall`, so unchanged sky frames preserve static adoption. A Proxy
1549
- replacing `runtime.sprites` itself is outside the contract: the deck
1550
- replaced an engine object. The descriptor and prototype checks, and the
1551
- small `{ art, image }` snapshot for a usable entry, run only with the sky
1552
- key on, once for each of the at most two textures drawn; there is no new
1553
- per-frame work with the sky key absent, whether or not static actors are on.
1554
-
1555
- **This relies on three.js's EventDispatcher internals, on purpose.** For a
1556
- texture, a geometry and a material, three.js's `dispose()` is
1557
- `dispatchEvent({ type: 'dispose' })` and nothing else, and `dispatchEvent`
1558
- stops at the first listener that throws. The renderer's own cleanup of the
1559
- GPU's copy is one of those listeners, added when the thing is first drawn
1560
- and so after any a deck added before that: one deck listener that throws
1561
- would leave the texture, the buffers or the program allocated for good,
1562
- whatever is caught round `dispose()`. So for the sky's own resources
1563
- `skylife.js` does not call `dispose()`: it reads the resource's
1564
- `_listeners.dispose` (EventDispatcher's own array), copies it, and calls
1565
- each listener in a try of its own with the event three.js would send. If
1566
- that array is not there in that shape it calls `dispose()` instead, in a
1567
- guard. `test-sky.mjs` fails if three.js keeps listeners elsewhere or its
1568
- `dispose()` comes to do more than dispatch: when it does after a three.js
1569
- upgrade, read `disposed` in `skylife.js` again before changing the test.
1570
-
1571
- While a record's resources are disposed, `world.sky` is a marker that is
1572
- not a record and owns nothing (`{ releasing: true }`), so that any frame a
1573
- `dispose` listener draws, an editor's or a keyless scene's included, is a
1574
- frame from inside: it makes nothing, and if it throws, the frame round the
1575
- disposal keeps no record. The marker is gone when the disposal ends.
1576
-
1577
- With the key absent, what runs that did not before: `load` reads
1578
- `data.engine.sky` once and stores null, and the physics system's `reset`
1579
- reads `world.sky` (null) once; each `renderWorld` reads that null and
1580
- `world.sky` and calls the frame it always was; `disposeWorld` reads
1581
- `world.sky` once. No call-out hook is acquired or allocated for a world
1582
- that never has a sky record.
1583
- - `"engine": { "maxFps": 60 }` at the scene file's top level (the same
1584
- `engine` object) asks the play loop (`engine3d/Scene3DPlayer.jsx`) not to
1585
- run its frame more often than that on a display that refreshes faster.
1586
- Without it the loop runs a whole frame (behaviours, physics, drawing) on
1587
- every animation frame the browser gives it, 120 a second on a 120 Hz
1588
- display; a scene that costs most of a frame there runs a core flat out and
1589
- drops every other frame. The terms:
1590
- > With the key absent, the loop runs exactly as before: every animation
1591
- > frame, handed the time since the last one, at most 0.033 s. With the key
1592
- > present, an animation frame runs the whole frame only when at least 78%
1593
- > of 1/maxFps seconds has passed since the last frame that ran, and is
1594
- > handed all of that time, at most 0.05 s, so nothing skipped is lost:
1595
- > a key pressed and let go, or a drag begun and ended, while frames were
1596
- > skipped is seen by the next frame that runs, as one frame would have
1597
- > seen it without the key. An animation frame that does not run does
1598
- > nothing at all. The first frame always runs.
1599
-
1600
- 0.05 s is three of physics' 1/60 s steps: physics takes at most four a
1601
- frame and drops what is left after four, so a longer frame (with what it
1602
- carries over) could leave physics behind the behaviours' clock; at most
1603
- 0.05 s a frame, the two keep the same time to within the one step physics
1604
- carries. That is why a cap is at least 30: a cap's frames are 1/maxFps
1605
- apart, under 0.05 s from 30 up, so the cut falls only on a late frame, as
1606
- 0.033 s does without the key. How input is lent (`engine3d/framecap.js`,
1607
- `updateLending`): the key handlers write down, under a cap only, every key
1608
- that went down and the stick's last direction while a drag held it; the
1609
- next frame that runs has each such key that is no longer held in
1610
- `runtime.keys` for its update, and that stick direction in
1611
- `runtime.moveInput` when no drag holds it now, and both are taken back
1612
- after the update. A key held across is seen as held, as always. A tap's
1613
- jump (`consumeJump`), the hub's grab key and its buttons keep their own
1614
- latches or act at once, and lose nothing.
1615
-
1616
- It goes by the time between frames, never by counting them; no frame is
1617
- made up after a late one. A browser only hands out frames on the display's
1618
- refresh, so the rule picks a whole number of refreshes per frame, and the
1619
- 78% is chosen so that each display gets one steady cadence at 60: every
1620
- refresh at 60 Hz (even with timestamps up to 1.8 ms early or late) and at
1621
- 75 Hz; every second at 90, 120 and 144 Hz (45, 60 and 72 fps); every
1622
- third at 165 and 180 Hz (55, 60); every fourth at 240 Hz (60). A cap is a
1623
- finite number from 30 to 240; anything else is no cap. It is read when
1624
- the scene loads (`runtime.maxFps`) and looked at every animation frame,
1625
- so going to a scene without it takes the cap off from the next frame on.
1626
- The scene and model editors run their own loops and are never capped.
1627
- Opt in when a scene costs enough that a fast display keeps the loop busy
1628
- all the time; a cheap scene loses smoothness on such a display and
1629
- gains nothing.
1630
-
1631
- The cap also changes how the `Player` hovers, as the camera key does:
1632
- under it the hover spring and the fall-faster pull are forces
1633
- (`hoverSteadily`, `pullSteadily`), with or without the camera key. Why:
1634
- the keyless hover and pull are impulses scaled by the frame's dt, pushed
1635
- once a frame, while gravity pulls once per fixed step, so each frame the
1636
- player gains g x (dt - steps x 1/60), which is g x (the change in
1637
- physics' accumulator carry). Its vertical speed follows the carry and its
1638
- drawn height bobs with it. Uncapped, a slow phone's frames longer than
1639
- 33 ms are all clamped to 0.033 s, two steps less 0.3 ms, so the carry
1640
- barely moves and the bob stays small; under the cap the same frames are
1641
- handed what they took (25 to 50 ms), the carry jumps anywhere in
1642
- [0, 1/60) every frame, and the bob grows. That was the TECNO KJ5's
1643
- tripled walking bob (3.2-3.4 cm against 1.05-1.16) that had the cap
1644
- reverted: measured before the hover became a force under the camera key,
1645
- so the town's Player was hovering by impulses then. Never the 3/60 clamp
1646
- itself: shrinking it would only cut more frames short.
1647
- `scripts/test-frame-cap-bob.mjs` drives the real Player and physics on
1648
- made-up frame timestamps through the real `nextFrame`; drawn height
1649
- peak to peak walking, in mm, without the camera key:
1650
-
1651
- | frames | uncapped | capped, impulse hover (reverted) | capped (now) |
1652
- | --- | --- | --- | --- |
1653
- | 60 Hz steady | 9.50 | 9.50 | 0.00 |
1654
- | 120 Hz, capped at 60 | 4.85 | 0.00 | 0.00 |
1655
- | slow phone, 25-55 ms + hitches (3 seeds) | 12.8-13.0 | 21.9-23.6 | 0.00 |
1656
- | slow phone, whole 90 Hz refreshes | 14.70 | 26.47 | 0.00 |
1657
- | slow phone, whole 60 Hz refreshes | 10.86 | 28.85 | 0.00 |
1658
-
1659
- With the camera key every cell is 0.00, capped or not; the walk's
1660
- horizontal speed is even in every cell (the walk push stays a per-frame
1661
- impulse: on flat ground nothing pushes against it per step, so at speed
1662
- it pushes nothing). The terms: with the key absent, `scene.maxFps` is 0
1663
- and the Player makes the calls it made before (test-steady-hover.mjs).
1664
- With it, the player stands and walks at the camera key's height, 0.7412 m
1665
- for the kit's player, whatever the frames, where the keyless player's
1666
- height depends on the frame rate (the damper answers the speed gravity
1667
- gave it since the last frame's push): 0.739 m at a steady 60 fps, 0.731
1668
- at 120, about 0.756 at 30. So a capped scene's player stands up to 1.5 cm
1669
- lower on a slow phone than the same scene uncapped, and 2 mm higher at
1670
- 60 fps; a player with another gravity scale is off by 0.69 cm per unit of
1671
- scale, as under the camera key. A jump goes as high as under the camera
1672
- key, to within 3 mm (2.347 to 2.355 m).
1673
-
1674
- The same dt variance moved the keyless follow camera (`updateCamera`). It
1675
- eases once a frame, from the Player's update, by 1 - e^(-12 dt) toward
1676
- where the player was drawn the frame before; behind a walk at v it trails
1677
- by about v/12 + v dt/2, and the player is then drawn v dt further on, so
1678
- under the cap the player slid about on screen (camera-to-player distance
1679
- peak to peak walking 39-52 mm against 12-19 uncapped on the slow-phone
1680
- traces). Under the cap, without a camera key, the Player asks for its
1681
- camera as the rigid one does (`scene.followCamera`, Player.jsx
1682
- `placeCapped`; `placeFollowCamera` in systems/physics3d.js now takes a
1683
- request from a scene with `maxFps` too): it is placed at the end of the
1684
- frame on the position the frame is drawn with, the same target and rate,
1685
- each coordinate eased as if the target moved steadily since the last
1686
- frame (`settle`, the exact solution of x' = 12 (target - x)), so a steady
1687
- walk is trailed by v/12 whatever the frames: that distance moves 0.00 mm
1688
- on every trace (4.3, 2.1 and 12-19 mm uncapped), and the camera's height
1689
- 0.00. Last frame's target is `actor.runtime.camTarget`; a teleport snaps
1690
- as it does uncapped. The orbit camera is under the camera key, placed at
1691
- the frame's end and eased exactly (or toward what the player asked, which
1692
- does not move with the walk) already, and is not changed.
1693
-
1694
- 60 is the tested cap: `RUN_SHARE`'s margins are worked out for it against
1695
- the common refresh rates. Other caps are allowed but thinner (a display
1696
- whose period sits near a multiple of 0.78/maxFps alternates cadences on
1697
- jittery timestamps), and a cap runs at a whole number of refreshes, not
1698
- at its own value: on a 60 Hz display a cap from 30 to about 46.8 runs at
1699
- 30 fps and one from about 46.8 up runs at 60. Because the capped keyless
1700
- camera is placed at the frame's end (as the rigid one is), a deck
1701
- behaviour that moves the camera during the update is overwritten there
1702
- under the cap. Releasing: the cap is read by physics-2d's
1703
- `SceneRuntime` (`maxFps`, latched at load) and acted on by physics-3d;
1704
- physics-3d pins the physics-2d it imports (`castle.json` `imports`), so
1705
- physics-2d must be republished and physics-3d's import of it moved before
1706
- the cap does anything in a deck. Until then `runtime.maxFps` is undefined,
1707
- every check above reads it as no cap, and the key is dormant.
1708
- Under the orbit camera key the drag stick is the orbit input's
1709
- (engine3d/orbitinput.js), which writes the same `runtime.moveInput`; the
1710
- move handler latches it under a cap as it does its own, so a stick drag
1711
- begun and ended between two capped frames is lent to the next frame that
1712
- runs too. Its camera drags are summed until the frame takes them, and lose
1713
- nothing.
64
+ - A scene file's top level may carry an `engine` object, beside `ground`.
65
+ Every key in it is opt-in: a scene without the key runs the engine exactly
66
+ as before. Each key's terms are in a file under `docs/`; read that file
67
+ before setting the key, or before changing code in a scene that sets it.
68
+ - `load` -- builds the models near the player before the first frame and
69
+ the rest in slices after it: docs/engine-load.md.
70
+ - `skipUnchangedActors`, `dropEmptyParts`, `skipEmptyNodes`,
71
+ `skipEmptyGaitHints` -- per-frame savings for a scene of hundreds of
72
+ mostly still actors: docs/engine-skip-work.md.
73
+ - `staticActors`, `frozenStatics` -- the engine leaves alone actors the
74
+ scene file marks `"static": true`. A write to a marked actor is not
75
+ followed unless `scene.touch(id)` comes first (`scene.touch?.(id)` under
76
+ an older kit): docs/engine-static-actors.md.
77
+ - `shadows` -- sun shadows drawn near the camera instead of in a fixed box:
78
+ docs/engine-shadows.md.
79
+ - `camera` -- `follow: "rigid"`, the `control: "orbit"` third-person
80
+ camera, and its `pitch`, `minPitch`, `distance` and `fov`; also the rule
81
+ for steady forces: docs/engine-camera.md.
82
+ - `view` -- view distance and fog: docs/engine-view.md.
83
+ - `look` -- models drawn first and their look baked after:
84
+ docs/engine-look.md.
85
+ - `sky` -- a sky per zone, fading between zones: docs/engine-sky.md.
86
+ - `maxFps` -- a cap on the play loop's frame rate:
87
+ docs/engine-frame-cap.md.
1714
88
  - `.scene` files open in the kit's 3d scene editor (same chrome as the 2d
1715
89
  kit's): blueprint hotbar (tap to inspect/edit the template, drag onto the
1716
90
  stage to place), orbit camera (drag orbits, wheel zooms), click to select /