castle-web-cli 0.4.232 → 0.4.234

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (587) hide show
  1. package/dist/agent-failures.d.ts +8 -0
  2. package/dist/agent-failures.js +19 -2
  3. package/dist/agent-prompts.d.ts +1 -1
  4. package/dist/agent-prompts.js +10 -3
  5. package/dist/agent.d.ts +64 -3
  6. package/dist/agent.js +170 -81
  7. package/dist/api.d.ts +11 -0
  8. package/dist/api.js +43 -0
  9. package/dist/bundle.d.ts +64 -0
  10. package/dist/bundle.js +558 -2
  11. package/dist/castle-host/host.d.ts +18 -2
  12. package/dist/castle-host/host.js +844 -39
  13. package/dist/castleJson.d.ts +23 -2
  14. package/dist/castleJson.js +46 -2
  15. package/dist/check.d.ts +3 -1
  16. package/dist/check.js +20 -3
  17. package/dist/chunkLoader.d.ts +3 -0
  18. package/dist/chunkLoader.js +111 -0
  19. package/dist/devParty.d.ts +26 -0
  20. package/dist/devParty.js +231 -0
  21. package/dist/devSaveStorage.js +4 -0
  22. package/dist/devSessionStorage.js +50 -2
  23. package/dist/devSocial.d.ts +24 -0
  24. package/dist/devSocial.js +70 -0
  25. package/dist/ide.d.ts +2 -0
  26. package/dist/ide.js +119 -15
  27. package/dist/importPinMismatch.d.ts +22 -0
  28. package/dist/importPinMismatch.js +77 -0
  29. package/dist/importRegression.js +3 -15
  30. package/dist/imports.d.ts +10 -3
  31. package/dist/imports.js +88 -20
  32. package/dist/index.js +11 -4
  33. package/dist/init.js +1 -1
  34. package/dist/platformDoc.js +22 -0
  35. package/dist/routerFences.d.ts +5 -0
  36. package/dist/routerFences.js +12 -2
  37. package/dist/save-deck.d.ts +25 -1
  38. package/dist/save-deck.js +178 -9
  39. package/dist/serve.js +32 -11
  40. package/dist/shell/assets/{index-D2tWM896.js → index-DulbYIJm.js} +97 -97
  41. package/dist/shell/assets/index-MVLfNYd9.css +1 -0
  42. package/dist/shell/index.html +2 -2
  43. package/dist/taskSteer.d.ts +13 -0
  44. package/dist/taskSteer.js +22 -2
  45. package/dist/vitePlugins.d.ts +2 -1
  46. package/dist/vitePlugins.js +13 -0
  47. package/kits/base/castle.json +1 -1
  48. package/kits/base/package-lock.json +1 -1
  49. package/kits/base/sdk/README.md +339 -5
  50. package/kits/base/sdk/avatar.d.ts +6 -2
  51. package/kits/base/sdk/avatar.js +12 -4
  52. package/kits/base/sdk/castle.d.ts +7 -3
  53. package/kits/base/sdk/castle.js +2 -0
  54. package/kits/base/sdk/commands.d.ts +176 -1
  55. package/kits/base/sdk/commands.js +3 -0
  56. package/kits/base/sdk/display.d.ts +3 -0
  57. package/kits/base/sdk/display.js +9 -3
  58. package/kits/base/sdk/hub.d.ts +37 -6
  59. package/kits/base/sdk/hub.js +63 -4
  60. package/kits/base/sdk/multiplayer.d.ts +7 -1
  61. package/kits/base/sdk/multiplayer.js +148 -32
  62. package/kits/base/sdk/multiplayerProtocol.d.ts +2 -0
  63. package/kits/base/sdk/party.d.ts +23 -0
  64. package/kits/base/sdk/party.js +91 -0
  65. package/kits/base/sdk/reconnectBudget.d.ts +23 -0
  66. package/kits/base/sdk/reconnectBudget.js +96 -0
  67. package/kits/base/sdk/save.d.ts +38 -1
  68. package/kits/base/sdk/save.js +81 -7
  69. package/kits/base/sdk/server/hub.d.ts +117 -0
  70. package/kits/base/sdk/server/hub.js +119 -2
  71. package/kits/base/sdk/server/platformHandle.d.ts +43 -1
  72. package/kits/base/sdk/server/storage.d.ts +17 -0
  73. package/kits/base/sdk/server/storage.js +65 -3
  74. package/kits/base/sdk/server/wrapper.d.ts +43 -6
  75. package/kits/base/sdk/server/wrapper.js +93 -9
  76. package/kits/base/sdk/social.d.ts +9 -0
  77. package/kits/base/sdk/social.js +5 -0
  78. package/kits/hub-game/CLAUDE.md +451 -13
  79. package/kits/hub-game/README.md +63 -0
  80. package/kits/hub-game/blueprints/avatar-10.scene +28 -0
  81. package/kits/hub-game/blueprints/avatar-11.scene +28 -0
  82. package/kits/hub-game/blueprints/avatar-12.scene +28 -0
  83. package/kits/hub-game/blueprints/avatar-13.scene +28 -0
  84. package/kits/hub-game/blueprints/avatar-14.scene +28 -0
  85. package/kits/hub-game/blueprints/avatar-15.scene +28 -0
  86. package/kits/hub-game/blueprints/avatar-4.scene +28 -0
  87. package/kits/hub-game/blueprints/avatar-5.scene +28 -0
  88. package/kits/hub-game/blueprints/avatar-6.scene +28 -0
  89. package/kits/hub-game/blueprints/avatar-7.scene +28 -0
  90. package/kits/hub-game/blueprints/avatar-8.scene +28 -0
  91. package/kits/hub-game/blueprints/avatar-9.scene +28 -0
  92. package/kits/hub-game/castle.json +5 -5
  93. package/kits/hub-game/code/client/act.js +312 -0
  94. package/kits/hub-game/code/client/actionLayout.js +147 -0
  95. package/kits/hub-game/code/client/actionOverflow.js +556 -0
  96. package/kits/hub-game/code/client/actorBudget.js +47 -0
  97. package/kits/hub-game/code/client/arrivalCamera.js +50 -0
  98. package/kits/hub-game/code/client/askSlot.js +117 -0
  99. package/kits/hub-game/code/client/attention.js +11 -2
  100. package/kits/hub-game/code/client/avatar.js +311 -35
  101. package/kits/hub-game/code/client/avatarCap.js +228 -0
  102. package/kits/hub-game/code/client/avatarColors.js +70 -0
  103. package/kits/hub-game/code/client/avatarFaces.js +21 -0
  104. package/kits/hub-game/code/client/avatarShare.js +253 -0
  105. package/kits/hub-game/code/client/backVisibility.js +13 -0
  106. package/kits/hub-game/code/client/ballot.js +472 -0
  107. package/kits/hub-game/code/client/build.js +38 -0
  108. package/kits/hub-game/code/client/chat.js +41 -5
  109. package/kits/hub-game/code/client/chatModeration.js +5 -0
  110. package/kits/hub-game/code/client/chrome.js +2144 -160
  111. package/kits/hub-game/code/client/companion.js +716 -0
  112. package/kits/hub-game/code/client/companionDress.js +99 -0
  113. package/kits/hub-game/code/client/crowdNames.js +241 -0
  114. package/kits/hub-game/code/client/decor.js +515 -0
  115. package/kits/hub-game/code/client/defaultEnvironment.js +194 -0
  116. package/kits/hub-game/code/client/doorErrors.js +39 -0
  117. package/kits/hub-game/code/client/earned.js +131 -0
  118. package/kits/hub-game/code/client/emoteBubble.js +75 -0
  119. package/kits/hub-game/code/client/fall.js +18 -0
  120. package/kits/hub-game/code/client/farAvatars.js +233 -0
  121. package/kits/hub-game/code/client/firstJoin.js +9 -2
  122. package/kits/hub-game/code/client/fpsTelemetry.js +50 -0
  123. package/kits/hub-game/code/client/frameBatch.js +5 -0
  124. package/kits/hub-game/code/client/grab.js +368 -29
  125. package/kits/hub-game/code/client/hookLayer.js +385 -20
  126. package/kits/hub-game/code/client/hudCopy.js +51 -0
  127. package/kits/hub-game/code/client/hudRate.js +20 -0
  128. package/kits/hub-game/code/client/idle.js +177 -24
  129. package/kits/hub-game/code/client/interestCap.js +81 -0
  130. package/kits/hub-game/code/client/invites.js +231 -0
  131. package/kits/hub-game/code/client/joinError.js +9 -0
  132. package/kits/hub-game/code/client/keys.js +36 -0
  133. package/kits/hub-game/code/client/labelsNear.js +234 -0
  134. package/kits/hub-game/code/client/landscapeLayout.js +17 -0
  135. package/kits/hub-game/code/client/layoutCache.js +264 -0
  136. package/kits/hub-game/code/client/loadTelemetry.js +20 -0
  137. package/kits/hub-game/code/client/loadingCover.js +148 -0
  138. package/kits/hub-game/code/client/loadingEntry.js +8 -0
  139. package/kits/hub-game/code/client/menuIcons.js +34 -0
  140. package/kits/hub-game/code/client/menuRows.js +43 -0
  141. package/kits/hub-game/code/client/modelReady.js +7 -0
  142. package/kits/hub-game/code/client/pack.js +6 -2
  143. package/kits/hub-game/code/client/packFormat.js +3 -3
  144. package/kits/hub-game/code/client/padCueArrival.js +23 -0
  145. package/kits/hub-game/code/client/padCues.js +112 -0
  146. package/kits/hub-game/code/client/padOccupancy.js +88 -0
  147. package/kits/hub-game/code/client/padReadability.js +26 -0
  148. package/kits/hub-game/code/client/padRings.js +69 -0
  149. package/kits/hub-game/code/client/pushVisit.js +14 -0
  150. package/kits/hub-game/code/client/quality.js +205 -0
  151. package/kits/hub-game/code/client/qualityEntry.js +55 -0
  152. package/kits/hub-game/code/client/rehello.js +167 -0
  153. package/kits/hub-game/code/client/safeLayout.js +338 -0
  154. package/kits/hub-game/code/client/safeStyle.js +42 -0
  155. package/kits/hub-game/code/client/say.js +12 -3
  156. package/kits/hub-game/code/client/shot.js +146 -0
  157. package/kits/hub-game/code/client/shotFit.js +56 -0
  158. package/kits/hub-game/code/client/signIn.js +28 -0
  159. package/kits/hub-game/code/client/sound.js +63 -8
  160. package/kits/hub-game/code/client/soundscape.js +1151 -0
  161. package/kits/hub-game/code/client/soundscapeActions.js +99 -0
  162. package/kits/hub-game/code/client/soundscapeAmbience.js +453 -0
  163. package/kits/hub-game/code/client/soundscapeBaked.js +143 -0
  164. package/kits/hub-game/code/client/soundscapeBusker.js +217 -0
  165. package/kits/hub-game/code/client/soundscapeCourt.js +200 -0
  166. package/kits/hub-game/code/client/soundscapeCrowd.js +331 -0
  167. package/kits/hub-game/code/client/soundscapeCues.js +362 -0
  168. package/kits/hub-game/code/client/soundscapeMap.js +181 -0
  169. package/kits/hub-game/code/client/soundscapeMarket.js +176 -0
  170. package/kits/hub-game/code/client/soundscapeMusic.js +126 -0
  171. package/kits/hub-game/code/client/soundscapeMusicEngine.js +460 -0
  172. package/kits/hub-game/code/client/soundscapeSimlish.js +737 -0
  173. package/kits/hub-game/code/client/soundscapeSongs.js +127 -0
  174. package/kits/hub-game/code/client/soundscapeSongsRound3.js +63 -0
  175. package/kits/hub-game/code/client/soundscapeSynthesis.js +168 -0
  176. package/kits/hub-game/code/client/soundscapeUi.js +211 -0
  177. package/kits/hub-game/code/client/soundscapeVoice.js +1209 -0
  178. package/kits/hub-game/code/client/soundscapeWaves.js +206 -0
  179. package/kits/hub-game/code/client/spin.js +101 -0
  180. package/kits/hub-game/code/client/state.js +162 -1
  181. package/kits/hub-game/code/client/stuck.js +259 -0
  182. package/kits/hub-game/code/client/talk.js +714 -59
  183. package/kits/hub-game/code/client/tiers.js +543 -52
  184. package/kits/hub-game/code/client/toastBand.js +37 -0
  185. package/kits/hub-game/code/client/together.js +39 -2
  186. package/kits/hub-game/code/client/visibility.js +43 -0
  187. package/kits/hub-game/code/client/weakestLookBake.js +92 -0
  188. package/kits/hub-game/code/client/weakestTier.js +295 -0
  189. package/kits/hub-game/code/client/wear.js +461 -170
  190. package/kits/hub-game/code/client/worldLabels.js +241 -0
  191. package/kits/hub-game/code/client/yours.js +200 -0
  192. package/kits/hub-game/code/companionSpec.js +45 -0
  193. package/kits/hub-game/code/npcDisplayText.js +55 -0
  194. package/kits/hub-game/code/privateText.js +7 -0
  195. package/kits/hub-game/code/server/act.js +124 -0
  196. package/kits/hub-game/code/server/actions.js +138 -0
  197. package/kits/hub-game/code/server/actors.js +11 -2
  198. package/kits/hub-game/code/server/analytics.js +83 -0
  199. package/kits/hub-game/code/server/anonymousEntry.js +49 -0
  200. package/kits/hub-game/code/server/arrivalPose.js +36 -0
  201. package/kits/hub-game/code/server/ask.js +155 -0
  202. package/kits/hub-game/code/server/ballot.js +539 -0
  203. package/kits/hub-game/code/server/cells.js +100 -0
  204. package/kits/hub-game/code/server/companion.js +107 -0
  205. package/kits/hub-game/code/server/cues.js +70 -0
  206. package/kits/hub-game/code/server/decor.js +269 -0
  207. package/kits/hub-game/code/server/doorAnalytics.js +52 -0
  208. package/kits/hub-game/code/server/earned.js +478 -0
  209. package/kits/hub-game/code/server/frameBatch.js +183 -0
  210. package/kits/hub-game/code/server/friendBests.js +166 -0
  211. package/kits/hub-game/code/server/friendsAmong.js +272 -0
  212. package/kits/hub-game/code/server/history.js +7 -0
  213. package/kits/hub-game/code/server/hub.js +2510 -95
  214. package/kits/hub-game/code/server/idle.js +60 -12
  215. package/kits/hub-game/code/server/index.js +28 -6
  216. package/kits/hub-game/code/server/invites.js +19 -0
  217. package/kits/hub-game/code/server/labels.js +36 -2
  218. package/kits/hub-game/code/server/loadAbandon.js +106 -0
  219. package/kits/hub-game/code/server/manifest.js +586 -7
  220. package/kits/hub-game/code/server/menu.js +161 -0
  221. package/kits/hub-game/code/server/npcs.js +1025 -113
  222. package/kits/hub-game/code/server/observe.js +408 -0
  223. package/kits/hub-game/code/server/padOccupancy.js +85 -0
  224. package/kits/hub-game/code/server/party.js +2 -2
  225. package/kits/hub-game/code/server/players.js +30 -0
  226. package/kits/hub-game/code/server/resumePose.js +152 -0
  227. package/kits/hub-game/code/server/say.js +1 -1
  228. package/kits/hub-game/code/server/shot.js +110 -0
  229. package/kits/hub-game/code/server/standing.js +123 -0
  230. package/kits/hub-game/code/server/storageLimit.js +187 -0
  231. package/kits/hub-game/code/server/vis.js +175 -0
  232. package/kits/hub-game/code/server/wear.js +12 -0
  233. package/kits/hub-game/code/server/yours.js +59 -0
  234. package/kits/hub-game/code/shared/act.js +35 -0
  235. package/kits/hub-game/code/shared/cues.js +9 -0
  236. package/kits/hub-game/code/shared/danceIdle.js +28 -0
  237. package/kits/hub-game/code/shared/decor.js +41 -0
  238. package/kits/hub-game/code/shared/loadStages.js +12 -0
  239. package/kits/hub-game/code/shared/quality.js +74 -0
  240. package/kits/hub-game/code/shared/say.js +2 -0
  241. package/kits/hub-game/code/shared/shot.js +53 -0
  242. package/kits/hub-game/code/shared/spin.js +57 -0
  243. package/kits/hub-game/code/systems/hub.js +1753 -202
  244. package/kits/hub-game/docs/analytics.md +279 -0
  245. package/kits/hub-game/docs/content-pack.md +1 -1
  246. package/kits/hub-game/docs/contract.md +3475 -77
  247. package/kits/hub-game/docs/home-pieces.md +71 -0
  248. package/kits/hub-game/docs/observed-progress.md +252 -0
  249. package/kits/hub-game/main.jsx +2 -0
  250. package/kits/hub-game/models/avatar-10.pxmodel +28 -0
  251. package/kits/hub-game/models/avatar-11.pxmodel +28 -0
  252. package/kits/hub-game/models/avatar-12.pxmodel +27 -0
  253. package/kits/hub-game/models/avatar-13.pxmodel +24 -0
  254. package/kits/hub-game/models/avatar-14.pxmodel +29 -0
  255. package/kits/hub-game/models/avatar-15.pxmodel +24 -0
  256. package/kits/hub-game/models/avatar-4.pxmodel +29 -0
  257. package/kits/hub-game/models/avatar-5.pxmodel +27 -0
  258. package/kits/hub-game/models/avatar-6.pxmodel +26 -0
  259. package/kits/hub-game/models/avatar-7.pxmodel +25 -0
  260. package/kits/hub-game/models/avatar-8.pxmodel +24 -0
  261. package/kits/hub-game/models/avatar-9.pxmodel +30 -0
  262. package/kits/hub-game/models/earned/badge-round.pxmodel +100 -0
  263. package/kits/hub-game/models/earned/badge-shield.pxmodel +117 -0
  264. package/kits/hub-game/models/earned/badge-star.pxmodel +87 -0
  265. package/kits/hub-game/models/earned/belt-plain.pxmodel +72 -0
  266. package/kits/hub-game/models/earned/held-ball.pxmodel +43 -0
  267. package/kits/hub-game/models/earned/held-lantern.pxmodel +85 -0
  268. package/kits/hub-game/models/earned/held-net.pxmodel +57 -0
  269. package/kits/hub-game/models/earned/held-trophy.pxmodel +109 -0
  270. package/kits/hub-game/models/earned/pin-round.pxmodel +62 -0
  271. package/kits/hub-game/models/earned/sash-plain.pxmodel +66 -0
  272. package/kits/hub-game/models/earned/square/belt-plain.pxmodel +104 -0
  273. package/kits/hub-game/models/earned/square/sash-plain.pxmodel +98 -0
  274. package/kits/hub-game/models/hats/bat-clip.pxmodel +206 -0
  275. package/kits/hub-game/models/hats/beekeeper.pxmodel +149 -0
  276. package/kits/hub-game/models/hats/cap.pxmodel +162 -0
  277. package/kits/hub-game/models/hats/captain.pxmodel +178 -0
  278. package/kits/hub-game/models/hats/crooked-top.pxmodel +172 -0
  279. package/kits/hub-game/models/hats/flower-crown.pxmodel +451 -0
  280. package/kits/hub-game/models/hats/foam-crown.pxmodel +179 -0
  281. package/kits/hub-game/models/hats/lantern.pxmodel +230 -0
  282. package/kits/hub-game/models/hats/laurel.pxmodel +533 -0
  283. package/kits/hub-game/models/hats/lighthouse.pxmodel +96 -0
  284. package/kits/hub-game/models/hats/sailor.pxmodel +141 -0
  285. package/kits/hub-game/models/hats/souwester.pxmodel +131 -0
  286. package/kits/hub-game/models/hats/straw.pxmodel +139 -0
  287. package/kits/hub-game/models/hats/sunflower.pxmodel +406 -0
  288. package/kits/hub-game/models/hats/sweatband.pxmodel +112 -0
  289. package/kits/hub-game/models/hats/witch.pxmodel +147 -0
  290. package/kits/hub-game/package-lock.json +10 -1
  291. package/kits/hub-game/package.json +6 -2
  292. package/kits/hub-game/play/player.js +142 -0
  293. package/kits/hub-game/play/registry.js +47 -0
  294. package/kits/hub-game/play.jsx +37 -0
  295. package/kits/hub-game/scripts/check.mjs +117 -16
  296. package/kits/hub-game/scripts/companion-follower-wire.json +1 -0
  297. package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +132 -0
  298. package/kits/hub-game/scripts/fixtures/decor-keyless.json +293 -0
  299. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +26 -0
  300. package/kits/hub-game/scripts/fixtures/fake-dom.mjs +123 -0
  301. package/kits/hub-game/scripts/fixtures/interest-legacy.json +385 -0
  302. package/kits/hub-game/scripts/fixtures/npc-notes-v1.77.jsonl +4 -0
  303. package/kits/hub-game/scripts/fixtures/vis-shared-wire.json +1 -0
  304. package/kits/hub-game/scripts/gen-avatars.mjs +933 -16
  305. package/kits/hub-game/scripts/gen-earned.mjs +285 -0
  306. package/kits/hub-game/scripts/gen-hats.mjs +827 -0
  307. package/kits/hub-game/scripts/grab.before-orbit.mjs +400 -0
  308. package/kits/hub-game/scripts/pose-storage-fixture.mjs +46 -0
  309. package/kits/hub-game/scripts/soundscape-wave-analysis.mjs +125 -0
  310. package/kits/hub-game/scripts/test-act-client.mjs +186 -0
  311. package/kits/hub-game/scripts/test-act.mjs +171 -0
  312. package/kits/hub-game/scripts/test-action-layout.mjs +80 -0
  313. package/kits/hub-game/scripts/test-action-observers.mjs +46 -0
  314. package/kits/hub-game/scripts/test-actions-client.mjs +853 -0
  315. package/kits/hub-game/scripts/test-actions.mjs +298 -0
  316. package/kits/hub-game/scripts/test-actor-budget.mjs +44 -0
  317. package/kits/hub-game/scripts/test-actors.mjs +38 -23
  318. package/kits/hub-game/scripts/test-analytics.mjs +76 -0
  319. package/kits/hub-game/scripts/test-anonymous-entry.mjs +28 -0
  320. package/kits/hub-game/scripts/test-arrival-pose-server.mjs +196 -0
  321. package/kits/hub-game/scripts/test-arrival-pose.mjs +24 -0
  322. package/kits/hub-game/scripts/test-ask-client.mjs +358 -0
  323. package/kits/hub-game/scripts/test-ask-slot.mjs +85 -0
  324. package/kits/hub-game/scripts/test-ask.mjs +269 -0
  325. package/kits/hub-game/scripts/test-attention.mjs +10 -1
  326. package/kits/hub-game/scripts/test-avatar-cap.mjs +379 -0
  327. package/kits/hub-game/scripts/test-avatar-colors.mjs +72 -0
  328. package/kits/hub-game/scripts/test-avatar-models.mjs +181 -0
  329. package/kits/hub-game/scripts/test-avatar-share.mjs +318 -0
  330. package/kits/hub-game/scripts/test-avatar-wire.mjs +792 -0
  331. package/kits/hub-game/scripts/test-avatar.mjs +584 -7
  332. package/kits/hub-game/scripts/test-back-visibility.mjs +82 -0
  333. package/kits/hub-game/scripts/test-ballot.mjs +1008 -0
  334. package/kits/hub-game/scripts/test-ban-join.mjs +121 -13
  335. package/kits/hub-game/scripts/test-build.mjs +49 -0
  336. package/kits/hub-game/scripts/test-cells.mjs +71 -0
  337. package/kits/hub-game/scripts/test-chat.mjs +863 -0
  338. package/kits/hub-game/scripts/test-classic.mjs +2 -0
  339. package/kits/hub-game/scripts/test-companion-chat.mjs +216 -0
  340. package/kits/hub-game/scripts/test-companion-client.mjs +1167 -0
  341. package/kits/hub-game/scripts/test-companion.mjs +259 -0
  342. package/kits/hub-game/scripts/test-control-layout-dom.mjs +120 -0
  343. package/kits/hub-game/scripts/test-crowd-names.mjs +205 -0
  344. package/kits/hub-game/scripts/test-decor-client.mjs +344 -0
  345. package/kits/hub-game/scripts/test-decor.mjs +464 -0
  346. package/kits/hub-game/scripts/test-default-environment-root.mjs +95 -0
  347. package/kits/hub-game/scripts/test-default-environment.mjs +267 -0
  348. package/kits/hub-game/scripts/test-door-analytics.mjs +58 -0
  349. package/kits/hub-game/scripts/test-door-jump.mjs +100 -0
  350. package/kits/hub-game/scripts/test-earned-client.mjs +459 -0
  351. package/kits/hub-game/scripts/test-earned.mjs +1224 -0
  352. package/kits/hub-game/scripts/test-emote-bubble.mjs +110 -0
  353. package/kits/hub-game/scripts/test-far-avatars.mjs +340 -0
  354. package/kits/hub-game/scripts/test-fps-telemetry.mjs +112 -0
  355. package/kits/hub-game/scripts/test-frame-batch.mjs +252 -0
  356. package/kits/hub-game/scripts/test-fresh-friends.mjs +118 -0
  357. package/kits/hub-game/scripts/test-friend-bests.mjs +435 -0
  358. package/kits/hub-game/scripts/test-grab-orbit.mjs +961 -0
  359. package/kits/hub-game/scripts/test-grab.mjs +7 -0
  360. package/kits/hub-game/scripts/test-hats.mjs +422 -168
  361. package/kits/hub-game/scripts/test-high-only.mjs +170 -0
  362. package/kits/hub-game/scripts/test-hub-leaving.mjs +203 -0
  363. package/kits/hub-game/scripts/test-hub-ops.mjs +758 -2
  364. package/kits/hub-game/scripts/test-hub-trip.mjs +1594 -12
  365. package/kits/hub-game/scripts/test-hud-clear.mjs +484 -57
  366. package/kits/hub-game/scripts/test-hud-defects-dom.mjs +100 -0
  367. package/kits/hub-game/scripts/test-hud-rate.mjs +224 -0
  368. package/kits/hub-game/scripts/test-hud-safe-visibility-dom.mjs +83 -0
  369. package/kits/hub-game/scripts/test-idle.mjs +427 -1
  370. package/kits/hub-game/scripts/test-interest-cap.mjs +36 -0
  371. package/kits/hub-game/scripts/test-interest-cells.mjs +513 -0
  372. package/kits/hub-game/scripts/test-interest-client.mjs +118 -0
  373. package/kits/hub-game/scripts/test-interest.mjs +15 -0
  374. package/kits/hub-game/scripts/test-invites-client.mjs +430 -0
  375. package/kits/hub-game/scripts/test-invites.mjs +109 -0
  376. package/kits/hub-game/scripts/test-keys.mjs +46 -1
  377. package/kits/hub-game/scripts/test-labels.mjs +664 -0
  378. package/kits/hub-game/scripts/test-landscape-layout.mjs +194 -0
  379. package/kits/hub-game/scripts/test-list-scroll-dom.mjs +49 -0
  380. package/kits/hub-game/scripts/test-load-abandon.mjs +246 -0
  381. package/kits/hub-game/scripts/test-loading-cover.mjs +162 -0
  382. package/kits/hub-game/scripts/test-manifest.mjs +472 -0
  383. package/kits/hub-game/scripts/test-menu-client.mjs +585 -0
  384. package/kits/hub-game/scripts/test-menu.mjs +319 -0
  385. package/kits/hub-game/scripts/test-npcs.mjs +2528 -13
  386. package/kits/hub-game/scripts/test-object-entry.mjs +76 -0
  387. package/kits/hub-game/scripts/test-observed.mjs +745 -0
  388. package/kits/hub-game/scripts/test-pack.mjs +7 -0
  389. package/kits/hub-game/scripts/test-pad-cues.mjs +304 -0
  390. package/kits/hub-game/scripts/test-pad-occupancy.mjs +177 -0
  391. package/kits/hub-game/scripts/test-picker.mjs +541 -0
  392. package/kits/hub-game/scripts/test-placement-cache.mjs +690 -0
  393. package/kits/hub-game/scripts/test-progress-reset.mjs +559 -0
  394. package/kits/hub-game/scripts/test-push-visit.mjs +26 -0
  395. package/kits/hub-game/scripts/test-quality.mjs +385 -0
  396. package/kits/hub-game/scripts/test-rehello.mjs +1733 -0
  397. package/kits/hub-game/scripts/test-relations-among.mjs +222 -0
  398. package/kits/hub-game/scripts/test-relations-refresh.mjs +188 -0
  399. package/kits/hub-game/scripts/test-resume-action-order.mjs +598 -0
  400. package/kits/hub-game/scripts/test-resume-held.mjs +239 -0
  401. package/kits/hub-game/scripts/test-resume-pose.mjs +142 -0
  402. package/kits/hub-game/scripts/test-safe-events-dom.mjs +116 -0
  403. package/kits/hub-game/scripts/test-safe-layout.mjs +330 -0
  404. package/kits/hub-game/scripts/test-say.mjs +1 -1
  405. package/kits/hub-game/scripts/test-shot.mjs +901 -0
  406. package/kits/hub-game/scripts/test-signin-client.mjs +45 -0
  407. package/kits/hub-game/scripts/test-soundscape.mjs +5437 -0
  408. package/kits/hub-game/scripts/test-spin.mjs +314 -0
  409. package/kits/hub-game/scripts/test-standing.mjs +449 -0
  410. package/kits/hub-game/scripts/test-storage-limit.mjs +333 -0
  411. package/kits/hub-game/scripts/test-stuck.mjs +1904 -0
  412. package/kits/hub-game/scripts/test-talk-overlay-dom.mjs +130 -0
  413. package/kits/hub-game/scripts/test-tier-cells.mjs +706 -0
  414. package/kits/hub-game/scripts/test-tiers-render.mjs +412 -0
  415. package/kits/hub-game/scripts/test-tiers.mjs +476 -2
  416. package/kits/hub-game/scripts/test-toast-band.mjs +61 -0
  417. package/kits/hub-game/scripts/test-try-on.mjs +22 -22
  418. package/kits/hub-game/scripts/test-vis.mjs +770 -0
  419. package/kits/hub-game/scripts/test-visibility.mjs +134 -0
  420. package/kits/hub-game/scripts/test-weakest-tier.mjs +924 -0
  421. package/kits/hub-game/scripts/test-world-labels.mjs +367 -0
  422. package/kits/hub-game/scripts/test-yours-chrome.mjs +210 -0
  423. package/kits/hub-game/scripts/test-yours.mjs +403 -0
  424. package/kits/multiplayer-3d/CLAUDE.md +50 -0
  425. package/kits/multiplayer-3d/castle.json +5 -5
  426. package/kits/multiplayer-3d/code/client/avatars.js +7 -0
  427. package/kits/multiplayer-3d/code/client/gait.js +65 -0
  428. package/kits/multiplayer-3d/code/client/joinFailure.js +27 -0
  429. package/kits/multiplayer-3d/code/client/nameTags.js +59 -4
  430. package/kits/multiplayer-3d/code/client/resumeGate.js +139 -0
  431. package/kits/multiplayer-3d/code/options.js +5 -0
  432. package/kits/multiplayer-3d/code/server/ownership.js +10 -2
  433. package/kits/multiplayer-3d/code/server/sceneBodies.js +12 -0
  434. package/kits/multiplayer-3d/code/server/world.js +7 -0
  435. package/kits/multiplayer-3d/code/systems/multiplayer.js +443 -34
  436. package/kits/multiplayer-3d/package-lock.json +8 -1
  437. package/kits/multiplayer-3d/package.json +3 -1
  438. package/kits/multiplayer-3d/scripts/fixtures/README.md +11 -0
  439. package/kits/multiplayer-3d/scripts/fixtures/ownership-legacy.json +2 -0
  440. package/kits/multiplayer-3d/scripts/ownership-harness.mjs +102 -0
  441. package/kits/multiplayer-3d/scripts/ownership-loader.mjs +46 -0
  442. package/kits/multiplayer-3d/scripts/ownership-worker.mjs +15 -0
  443. package/kits/multiplayer-3d/scripts/record-ownership-session.mjs +98 -0
  444. package/kits/multiplayer-3d/scripts/test-eligible-claims.mjs +167 -0
  445. package/kits/multiplayer-3d/scripts/test-join-watchdog.mjs +436 -0
  446. package/kits/multiplayer-3d/scripts/test-own-name-tag.mjs +247 -0
  447. package/kits/multiplayer-3d/scripts/test-resume-gate.mjs +624 -0
  448. package/kits/physics-2d/CLAUDE.md +19 -1
  449. package/kits/physics-2d/castle.json +2 -2
  450. package/kits/physics-2d/engine/frozenActors.js +233 -0
  451. package/kits/physics-2d/engine/scene.js +337 -3
  452. package/kits/physics-2d/engine/skyKey.js +129 -0
  453. package/kits/physics-2d/engine/stillClock.js +106 -0
  454. package/kits/physics-2d/engine/updateBudget.js +21 -0
  455. package/kits/physics-2d/eslint.config.js +1 -1
  456. package/kits/physics-2d/play/behaviors/AnalogStick.js +198 -0
  457. package/kits/physics-2d/play/behaviors/Camera.js +40 -0
  458. package/kits/physics-2d/play/behaviors/Collider.js +122 -0
  459. package/kits/physics-2d/play/behaviors/Draggable.js +115 -0
  460. package/kits/physics-2d/play/behaviors/Goal.js +46 -0
  461. package/kits/physics-2d/play/behaviors/Joints.js +126 -0
  462. package/kits/physics-2d/play/behaviors/Layout.js +71 -0
  463. package/kits/physics-2d/play/behaviors/RigidBody.js +57 -0
  464. package/kits/physics-2d/play/behaviors/Slingshot.js +142 -0
  465. package/kits/physics-2d/play/behaviors/SoundPlayer.js +263 -0
  466. package/kits/physics-2d/play/behaviors/Sprite.js +406 -0
  467. package/kits/physics-2d/play/behaviors/Style.js +209 -0
  468. package/kits/physics-2d/play/behaviors/Text.js +85 -0
  469. package/kits/physics-2d/play/behaviors/Video.js +93 -0
  470. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +326 -1
  471. package/kits/physics-3d/CLAUDE.md +42 -529
  472. package/kits/physics-3d/behaviors/Body.jsx +3 -0
  473. package/kits/physics-3d/behaviors/Model.jsx +3 -0
  474. package/kits/physics-3d/behaviors/Player.jsx +661 -87
  475. package/kits/physics-3d/behaviors/Shape.jsx +3 -0
  476. package/kits/physics-3d/behaviors/Solid.jsx +3 -0
  477. package/kits/physics-3d/behaviors/Transform.jsx +3 -0
  478. package/kits/physics-3d/castle.json +3 -3
  479. package/kits/physics-3d/docs/engine-camera.md +542 -0
  480. package/kits/physics-3d/docs/engine-frame-cap.md +136 -0
  481. package/kits/physics-3d/docs/engine-load.md +149 -0
  482. package/kits/physics-3d/docs/engine-look.md +114 -0
  483. package/kits/physics-3d/docs/engine-shadows.md +372 -0
  484. package/kits/physics-3d/docs/engine-skip-work.md +187 -0
  485. package/kits/physics-3d/docs/engine-sky.md +198 -0
  486. package/kits/physics-3d/docs/engine-static-actors.md +226 -0
  487. package/kits/physics-3d/docs/engine-view.md +37 -0
  488. package/kits/physics-3d/docs/pxmodel-format.md +9 -1
  489. package/kits/physics-3d/engine3d/PlayOnly3D.jsx +5 -1
  490. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +19 -277
  491. package/kits/physics-3d/engine3d/actornode.js +87 -0
  492. package/kits/physics-3d/engine3d/animationBudget.js +23 -0
  493. package/kits/physics-3d/engine3d/branches.js +3 -13
  494. package/kits/physics-3d/engine3d/cage.js +2 -7
  495. package/kits/physics-3d/engine3d/cageops.js +2 -17
  496. package/kits/physics-3d/engine3d/dataBehaviors.js +12 -0
  497. package/kits/physics-3d/engine3d/editorWorld.js +6 -0
  498. package/kits/physics-3d/engine3d/emptynodes.js +232 -0
  499. package/kits/physics-3d/engine3d/framecap.js +99 -0
  500. package/kits/physics-3d/engine3d/frozenphysics.js +140 -0
  501. package/kits/physics-3d/engine3d/frozenstatics.js +273 -0
  502. package/kits/physics-3d/engine3d/gait.js +126 -0
  503. package/kits/physics-3d/engine3d/initialModelFiles.js +18 -0
  504. package/kits/physics-3d/engine3d/kithooks.js +47 -0
  505. package/kits/physics-3d/engine3d/look.js +514 -48
  506. package/kits/physics-3d/engine3d/lookbake.js +208 -0
  507. package/kits/physics-3d/engine3d/materialpresets.js +2 -0
  508. package/kits/physics-3d/engine3d/modelFiles.js +3 -17
  509. package/kits/physics-3d/engine3d/modelMath.js +49 -0
  510. package/kits/physics-3d/engine3d/modelready.js +16 -0
  511. package/kits/physics-3d/engine3d/motion.js +39 -10
  512. package/kits/physics-3d/engine3d/nearshadows.js +106 -21
  513. package/kits/physics-3d/engine3d/optimize.js +9 -5
  514. package/kits/physics-3d/engine3d/orbitinput.js +522 -10
  515. package/kits/physics-3d/engine3d/orbitlens.js +48 -0
  516. package/kits/physics-3d/engine3d/ownmodel.js +213 -0
  517. package/kits/physics-3d/engine3d/partgeometry.js +1 -16
  518. package/kits/physics-3d/engine3d/paths.js +1 -9
  519. package/kits/physics-3d/engine3d/playTimings.js +50 -0
  520. package/kits/physics-3d/engine3d/playerRun.js +372 -0
  521. package/kits/physics-3d/engine3d/pxmodel.js +42 -11
  522. package/kits/physics-3d/engine3d/rapier.js +27 -0
  523. package/kits/physics-3d/engine3d/scatter.js +1 -11
  524. package/kits/physics-3d/engine3d/shadowfade.js +890 -0
  525. package/kits/physics-3d/engine3d/sky.js +547 -0
  526. package/kits/physics-3d/engine3d/skylife.js +306 -0
  527. package/kits/physics-3d/engine3d/squarefirst.js +177 -0
  528. package/kits/physics-3d/engine3d/stillshadows.js +399 -0
  529. package/kits/physics-3d/engine3d/sweep.js +1 -25
  530. package/kits/physics-3d/engine3d/unchanged.js +11 -0
  531. package/kits/physics-3d/engine3d/viewrange.js +52 -0
  532. package/kits/physics-3d/engine3d/world3d.js +1253 -76
  533. package/kits/physics-3d/eslint.config.js +2 -1
  534. package/kits/physics-3d/main.jsx +10 -2
  535. package/kits/physics-3d/package-lock.json +7 -0
  536. package/kits/physics-3d/package.json +5 -1
  537. package/kits/physics-3d/play/behaviors/Body.js +31 -0
  538. package/kits/physics-3d/play/behaviors/Door.js +37 -0
  539. package/kits/physics-3d/play/behaviors/Lookable.js +16 -0
  540. package/kits/physics-3d/play/behaviors/Model.js +23 -0
  541. package/kits/physics-3d/play/behaviors/Pickup.js +46 -0
  542. package/kits/physics-3d/play/behaviors/Player.js +1204 -0
  543. package/kits/physics-3d/play/behaviors/Shape.js +47 -0
  544. package/kits/physics-3d/play/behaviors/Solid.js +16 -0
  545. package/kits/physics-3d/play/behaviors/Transform.js +29 -0
  546. package/kits/physics-3d/pnpm-lock.yaml +8 -0
  547. package/kits/physics-3d/scripts/bench-shadow-fade.mjs +37 -0
  548. package/kits/physics-3d/scripts/build-rapier-gz.mjs +56 -0
  549. package/kits/physics-3d/scripts/frozen-statics-fixture.mjs +141 -0
  550. package/kits/physics-3d/scripts/look-baseline.mjs +155 -0
  551. package/kits/physics-3d/scripts/test-camera-follow.mjs +5 -1
  552. package/kits/physics-3d/scripts/test-camera-orbit.mjs +2613 -82
  553. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +2 -2
  554. package/kits/physics-3d/scripts/test-empty-gait-hints.mjs +89 -0
  555. package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +438 -0
  556. package/kits/physics-3d/scripts/test-frame-cap.mjs +452 -0
  557. package/kits/physics-3d/scripts/test-frozen-nested.mjs +49 -0
  558. package/kits/physics-3d/scripts/test-frozen-statics-legacy-physics2d.mjs +123 -0
  559. package/kits/physics-3d/scripts/test-frozen-statics.mjs +434 -0
  560. package/kits/physics-3d/scripts/test-gait.mjs +387 -0
  561. package/kits/physics-3d/scripts/test-look-bake.mjs +1056 -0
  562. package/kits/physics-3d/scripts/test-model-parse-cache.mjs +92 -0
  563. package/kits/physics-3d/scripts/test-near-shadows.mjs +5 -2
  564. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +2001 -0
  565. package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +582 -0
  566. package/kits/physics-3d/scripts/test-orbit-shot.mjs +657 -0
  567. package/kits/physics-3d/scripts/test-orbit-view.mjs +230 -0
  568. package/kits/physics-3d/scripts/test-rapier-gz.mjs +106 -0
  569. package/kits/physics-3d/scripts/test-skip-empty-nodes.mjs +845 -0
  570. package/kits/physics-3d/scripts/test-sky.mjs +2470 -0
  571. package/kits/physics-3d/scripts/test-square-first.mjs +921 -0
  572. package/kits/physics-3d/scripts/test-static-actors.mjs +10 -1
  573. package/kits/physics-3d/scripts/test-static-physics.mjs +4 -1
  574. package/kits/physics-3d/scripts/test-static-scenery.mjs +2174 -0
  575. package/kits/physics-3d/scripts/test-steady-hover.mjs +7 -2
  576. package/kits/physics-3d/scripts/test-still-shadows.mjs +477 -0
  577. package/kits/physics-3d/scripts/test-view-range.mjs +260 -0
  578. package/kits/physics-3d/systems/physics3d.js +419 -9
  579. package/kits/real-time/castle.json +2 -2
  580. package/kits/real-time/code/client/connection.js +33 -10
  581. package/kits/real-time/code/client/gameHooks.js +2 -0
  582. package/kits/real-time/code/client/joinOverlay.js +9 -4
  583. package/kits/real-time/code/server/gameHooks.js +7 -0
  584. package/kits/real-time/code/server/session.js +102 -22
  585. package/kits/real-time/package-lock.json +1 -1
  586. package/package.json +2 -2
  587. package/dist/shell/assets/index-Cf61cNfT.css +0 -1
@@ -0,0 +1,136 @@
1
+ # Scene key: engine.maxFps
2
+
3
+ The physics-3d kit's CLAUDE.md Quick reference points here. The key sits in
4
+ the `engine` object at a scene file's top level, beside `ground`.
5
+
6
+ - `"engine": { "maxFps": 60 }` at the scene file's top level (the same
7
+ `engine` object) asks the play loop (`engine3d/Scene3DPlayer.jsx`) not to
8
+ run its frame more often than that on a display that refreshes faster.
9
+ Without it the loop runs a whole frame (behaviours, physics, drawing) on
10
+ every animation frame the browser gives it, 120 a second on a 120 Hz
11
+ display; a scene that costs most of a frame there runs a core flat out and
12
+ drops every other frame. The terms:
13
+ > With the key absent, the loop runs exactly as before: every animation
14
+ > frame, handed the time since the last one, at most 0.033 s. With the key
15
+ > present, an animation frame runs the whole frame only when at least 78%
16
+ > of 1/maxFps seconds has passed since the last frame that ran, and is
17
+ > handed all of that time, at most 0.05 s, so nothing skipped is lost:
18
+ > a key pressed and let go, or a drag begun and ended, while frames were
19
+ > skipped is seen by the next frame that runs, as one frame would have
20
+ > seen it without the key. An animation frame that does not run does
21
+ > nothing at all. The first frame always runs.
22
+
23
+ 0.05 s is three of physics' 1/60 s steps: physics takes at most four a
24
+ frame and drops what is left after four, so a longer frame (with what it
25
+ carries over) could leave physics behind the behaviours' clock; at most
26
+ 0.05 s a frame, the two keep the same time to within the one step physics
27
+ carries. That is why a cap is at least 30: a cap's frames are 1/maxFps
28
+ apart, under 0.05 s from 30 up, so the cut falls only on a late frame, as
29
+ 0.033 s does without the key. How input is lent (`engine3d/framecap.js`,
30
+ `updateLending`): the key handlers write down, under a cap only, every key
31
+ that went down and the stick's last direction while a drag held it; the
32
+ next frame that runs has each such key that is no longer held in
33
+ `runtime.keys` for its update, and that stick direction in
34
+ `runtime.moveInput` when no drag holds it now, and both are taken back
35
+ after the update. A key held across is seen as held, as always. A tap's
36
+ jump (`consumeJump`), the hub's grab key and its buttons keep their own
37
+ latches or act at once, and lose nothing.
38
+
39
+ It goes by the time between frames, never by counting them; no frame is
40
+ made up after a late one. A browser only hands out frames on the display's
41
+ refresh, so the rule picks a whole number of refreshes per frame, and the
42
+ 78% is chosen so that each display gets one steady cadence at 60: every
43
+ refresh at 60 Hz (even with timestamps up to 1.8 ms early or late) and at
44
+ 75 Hz; every second at 90, 120 and 144 Hz (45, 60 and 72 fps); every
45
+ third at 165 and 180 Hz (55, 60); every fourth at 240 Hz (60). A cap is a
46
+ finite number from 30 to 240; anything else is no cap. It is read when
47
+ the scene loads (`runtime.maxFps`) and looked at every animation frame,
48
+ so going to a scene without it takes the cap off from the next frame on.
49
+ The scene and model editors run their own loops and are never capped.
50
+ Opt in when a scene costs enough that a fast display keeps the loop busy
51
+ all the time; a cheap scene loses smoothness on such a display and
52
+ gains nothing.
53
+
54
+ The cap also changes how the `Player` hovers, as the camera key does:
55
+ under it the hover spring and the fall-faster pull are forces
56
+ (`hoverSteadily`, `pullSteadily`), with or without the camera key. Why:
57
+ the keyless hover and pull are impulses scaled by the frame's dt, pushed
58
+ once a frame, while gravity pulls once per fixed step, so each frame the
59
+ player gains g x (dt - steps x 1/60), which is g x (the change in
60
+ physics' accumulator carry). Its vertical speed follows the carry and its
61
+ drawn height bobs with it. Uncapped, a slow phone's frames longer than
62
+ 33 ms are all clamped to 0.033 s, two steps less 0.3 ms, so the carry
63
+ barely moves and the bob stays small; under the cap the same frames are
64
+ handed what they took (25 to 50 ms), the carry jumps anywhere in
65
+ [0, 1/60) every frame, and the bob grows. That was the TECNO KJ5's
66
+ tripled walking bob (3.2-3.4 cm against 1.05-1.16) that had the cap
67
+ reverted: measured before the hover became a force under the camera key,
68
+ so the town's Player was hovering by impulses then. Never the 3/60 clamp
69
+ itself: shrinking it would only cut more frames short.
70
+ `scripts/test-frame-cap-bob.mjs` drives the real Player and physics on
71
+ made-up frame timestamps through the real `nextFrame`; drawn height
72
+ peak to peak walking, in mm, without the camera key:
73
+
74
+ | frames | uncapped | capped, impulse hover (reverted) | capped (now) |
75
+ | --- | --- | --- | --- |
76
+ | 60 Hz steady | 9.50 | 9.50 | 0.00 |
77
+ | 120 Hz, capped at 60 | 4.85 | 0.00 | 0.00 |
78
+ | slow phone, 25-55 ms + hitches (3 seeds) | 12.8-13.0 | 21.9-23.6 | 0.00 |
79
+ | slow phone, whole 90 Hz refreshes | 14.70 | 26.47 | 0.00 |
80
+ | slow phone, whole 60 Hz refreshes | 10.86 | 28.85 | 0.00 |
81
+
82
+ With the camera key every cell is 0.00, capped or not; the walk's
83
+ horizontal speed is even in every cell (the walk push stays a per-frame
84
+ impulse: on flat ground nothing pushes against it per step, so at speed
85
+ it pushes nothing). The terms: with the key absent, `scene.maxFps` is 0
86
+ and the Player makes the calls it made before (test-steady-hover.mjs).
87
+ With it, the player stands and walks at the camera key's height, 0.7412 m
88
+ for the kit's player, whatever the frames, where the keyless player's
89
+ height depends on the frame rate (the damper answers the speed gravity
90
+ gave it since the last frame's push): 0.739 m at a steady 60 fps, 0.731
91
+ at 120, about 0.756 at 30. So a capped scene's player stands up to 1.5 cm
92
+ lower on a slow phone than the same scene uncapped, and 2 mm higher at
93
+ 60 fps; a player with another gravity scale is off by 0.69 cm per unit of
94
+ scale, as under the camera key. A jump goes as high as under the camera
95
+ key, to within 3 mm (2.347 to 2.355 m).
96
+
97
+ The same dt variance moved the keyless follow camera (`updateCamera`). It
98
+ eases once a frame, from the Player's update, by 1 - e^(-12 dt) toward
99
+ where the player was drawn the frame before; behind a walk at v it trails
100
+ by about v/12 + v dt/2, and the player is then drawn v dt further on, so
101
+ under the cap the player slid about on screen (camera-to-player distance
102
+ peak to peak walking 39-52 mm against 12-19 uncapped on the slow-phone
103
+ traces). Under the cap, without a camera key, the Player asks for its
104
+ camera as the rigid one does (`scene.followCamera`, Player.jsx
105
+ `placeCapped`; `placeFollowCamera` in systems/physics3d.js now takes a
106
+ request from a scene with `maxFps` too): it is placed at the end of the
107
+ frame on the position the frame is drawn with, the same target and rate,
108
+ each coordinate eased as if the target moved steadily since the last
109
+ frame (`settle`, the exact solution of x' = 12 (target - x)), so a steady
110
+ walk is trailed by v/12 whatever the frames: that distance moves 0.00 mm
111
+ on every trace (4.3, 2.1 and 12-19 mm uncapped), and the camera's height
112
+ 0.00. Last frame's target is `actor.runtime.camTarget`; a teleport snaps
113
+ as it does uncapped. The orbit camera is under the camera key, placed at
114
+ the frame's end and eased exactly (or toward what the player asked, which
115
+ does not move with the walk) already, and is not changed.
116
+
117
+ 60 is the tested cap: `RUN_SHARE`'s margins are worked out for it against
118
+ the common refresh rates. Other caps are allowed but thinner (a display
119
+ whose period sits near a multiple of 0.78/maxFps alternates cadences on
120
+ jittery timestamps), and a cap runs at a whole number of refreshes, not
121
+ at its own value: on a 60 Hz display a cap from 30 to about 46.8 runs at
122
+ 30 fps and one from about 46.8 up runs at 60. Because the capped keyless
123
+ camera is placed at the frame's end (as the rigid one is), a deck
124
+ behaviour that moves the camera during the update is overwritten there
125
+ under the cap. Releasing: the cap is read by physics-2d's
126
+ `SceneRuntime` (`maxFps`, latched at load) and acted on by physics-3d;
127
+ physics-3d pins the physics-2d it imports (`castle.json` `imports`), so
128
+ physics-2d must be republished and physics-3d's import of it moved before
129
+ the cap does anything in a deck. Until then `runtime.maxFps` is undefined,
130
+ every check above reads it as no cap, and the key is dormant.
131
+ Under the orbit camera key the drag stick is the orbit input's
132
+ (engine3d/orbitinput.js), which writes the same `runtime.moveInput`; the
133
+ move handler latches it under a cap as it does its own, so a stick drag
134
+ begun and ended between two capped frames is lent to the next frame that
135
+ runs too. Its camera drags are summed until the frame takes them, and lose
136
+ nothing.
@@ -0,0 +1,149 @@
1
+ # Scene key: engine.load
2
+
3
+ The physics-3d kit's CLAUDE.md Quick reference points here. The key sits in
4
+ the `engine` object at a scene file's top level, beside `ground`.
5
+
6
+ - `"engine": { "load": { "first": { "radius": 30 }, "sliceMs": 8 } }`
7
+ builds the square's model visuals before the first frame and the remaining
8
+ models in slices after it. This is dormant unless the scene explicitly sets
9
+ the key; the editor (`world.staticActorsOff`) keeps synchronous visuals.
10
+ `engine3d/squarefirst.js` validates the complete key: `first` is
11
+ either an object containing only a finite `radius > 0` in metres, or an
12
+ array of nonempty actor-id strings (an empty array is allowed). `sliceMs`
13
+ is optional, defaults to 8, and must be a finite number from 1 through 50.
14
+ Optional `horizon` is a finite number of metres >= 0, default 45. It limits
15
+ background builds to pending keys with at least one waiting actor within
16
+ that x/z distance of the current first Player actor's Transform, including
17
+ the boundary; without that Transform it uses the camera's world position.
18
+ Unlike first-sync selection, this horizon follows movement. `horizon: 0`
19
+ disables the distance limit and lets the background drain build every key.
20
+ Eligibility is cached until the player (or fallback camera) moves more than
21
+ 1 m in x/z from the last sample, or pending membership/placement changes.
22
+ Sub-metre boundary crossings may therefore wait for the next sample. Sync
23
+ invalidates moving waiters too, including dynamic and tier-detached actors.
24
+ Optional `inert` is an array of nonempty component-name strings (empty is
25
+ allowed), e.g. `["Lookable", "RouteAnchor", "WalkSurface"]`: the deck
26
+ promises those components never consume their actor's visual, even when
27
+ registered on the client.
28
+ Unknown fields, missing `first`, or any invalid value disable the whole
29
+ key; absent/invalid keys retain the synchronous node trees and build calls.
30
+
31
+ Radius uses x/z distance, including the boundary. Its centre is the first
32
+ actor with a `Player` component's Transform at the scene's first sync, or
33
+ the origin if none exists. The centre and selected keys do not move as the
34
+ player moves. With `"first": ["ground", "fountain"]`, those actors select
35
+ their model keys instead. Every copy of a selected key is first, regardless
36
+ of its own distance. Models shared with any unsafe-to-wait actor are first
37
+ too, even when that actor occurs later in the actor list.
38
+
39
+ The wait predicate allows unregistered components (pure scene data: the
40
+ shared SceneRuntime creates no instance or callbacks for them) and declared
41
+ `inert` components. Registered client behaviours otherwise block, even
42
+ disabled or constructor-only custom classes. The kit's Transform, Shape,
43
+ Model, Solid and Body classes are data-only exceptions by exact class
44
+ registration in `engine3d/dataBehaviors.js`. Their canonical behaviour
45
+ modules and generated play mirrors register their own classes in the same
46
+ WeakSet; the predicate imports neither inspectors nor editor modules.
47
+ Replacements and subclasses block unless declared inert, including
48
+ constructors that assign their own update/collision functions. Body may be
49
+ fixed, kinematic or dynamic: `systems/physics3d.js` builds colliders from
50
+ Shape, places bodies from Transform and writes motion back to Transform;
51
+ neither it nor `engine3d/frozenphysics.js` reads model rigs or parts.
52
+ Player always blocks, including when unregistered or declared inert, as do
53
+ requested model clips, follow-camera/own-model actors and registered
54
+ own-model attachments. The model and its references must have no motion, clips, gait
55
+ or biped part ids (`legL`, `legR`, `armL`, `armR`, `torso`), nor parts marked
56
+ `keep`, `tint`, or named `slot-*`. `instanceModels` stays synchronous. Scene
57
+ code opting in must not inspect or alter these deferred actors' visual
58
+ subtrees/parts until they are ready. Colliders, bodies, actor transforms
59
+ and behaviours still initialize and run on their original schedule.
60
+ When `runtime.callsBeforeBehavior === true` explicitly advertises support,
61
+ the runtime's optional `beforeBehavior(actor, name)` fence promotes actors
62
+ that stop being safe to wait immediately before
63
+ instance creation or dispatch. This covers a new registered class, a
64
+ component added during another behaviour's update, enabled transitions,
65
+ direct `behavior()` access, taps and collision callbacks. The previous
66
+ fence is chained and restored when the load is cleared.
67
+
68
+ Older published physics-2d runtimes do not advertise that capability; no
69
+ fence is installed on them. Deferred loading still works: physics-3d checks
70
+ cheap consumer fingerprints before each player update (ordinary and capped).
71
+ Waiters compare component count, membership and each captured registered
72
+ class identity, detecting registration swaps even at unchanged Map size.
73
+ Unchanged waiters allocate no new key list and use one Map lookup per component.
74
+ A remove+add preserving the count promotes conservatively. This path never
75
+ constructs model/node signatures: signatures are still rechecked at fill
76
+ and normal sync. Collision dispatch checks only each pair actor's own wait,
77
+ again before its callback, without visiting unrelated pending keys.
78
+ Taps dispatch inside runtime.update and receive that pre-update check too.
79
+ Thus behaviour registrations and component additions made between frames
80
+ promote before their first callback. The remaining legacy gap is a consumer
81
+ added to a waiting actor and first run within the same runtime.update pass,
82
+ before the next physics-3d check (or a direct nested dispatch inside that
83
+ runtime pass). Such code must call ensureActorModel before using the visual;
84
+ the per-consumer fence closes this gap on runtimes advertising support.
85
+
86
+ Readers that retain, clone or measure another actor's model must call
87
+ `ensureActorModel(world, actorId)` first, then look up its node again. This
88
+ synchronous promotion is exported by `engine3d/modelready.js` and re-exported
89
+ by `world3d.js`; it fills the whole shared key through the normal fill path,
90
+ without draining unrelated keys. It is a no-op for complete/missing actors
91
+ and without the load key. Hub decor, avatar sharing/proxies and idle rig
92
+ readers use it. Companion and wear build independent visuals attached beside
93
+ actor rigs, so do not consume their model; weakest-look sorting skips unbuilt
94
+ models, which have no bake task yet, and reorders when a fill adds tasks.
95
+
96
+ A waiting actor keeps its placed node and an empty rig at the same yOffset
97
+ and scale. The rig and `node.userData.modelParts` Map retain their identities;
98
+ filling adds the model children and Map entries in place. A model reduced
99
+ to nothing by `dropEmptyParts` removes its placeholder rig. `skipEmptyNodes`
100
+ cannot detach a waiting rig as empty. External tier/decor detachment and
101
+ renderSleep remain owned by their controllers: filling does not reattach
102
+ or wake them. Frozen subtrees are thawed and their new matrices updated.
103
+ Every waiting copy's signature is checked again immediately before fill,
104
+ including after another copy's listener ran. A stale signature discards the
105
+ waiting node and rebuilds synchronously through ordinary placement using
106
+ current data. Its fresh root is attached for tier adoption even if the old
107
+ one was detached with renderSleep; the engine leaves the sleep flag owned
108
+ by the controller. This avoids a missing replacement that no controller owns.
109
+ After each waiting actor is filled and its matrices updated, the engine
110
+ dispatches `{ type: 'modelfilled', actorId, node }` on `world.scene` (a
111
+ three.js EventDispatcher). This includes models reduced to empty; it never
112
+ fires for synchronous builds or cancelled waits. Consumers can use
113
+ `world.scene.addEventListener('modelfilled', listener)` to invalidate bounds
114
+ cached under the unchanged node identity, and must remove their listener
115
+ when leaving that world. Hub-game subscribes only while `world.modelLoad`
116
+ exists, drops that node's distance bound and requests a fresh tier pass.
117
+
118
+ The first render arms the queue without building. After subsequent rendered
119
+ frames, eligible keys inside the horizon are prioritized by camera distance
120
+ (the nearest of each key's waiting copies), through the ordinary shared
121
+ `takeModel` path, with ordinary drop-empty and deferred-look handling. All
122
+ waiting copies of that key are filled together, even copies outside the
123
+ horizon. Farther keys remain pending until movement brings a copy in range.
124
+
125
+ The drain measures intervals between actual draws, before deferred look
126
+ baking. If the latest interval exceeds max(2 x the median of the previous
127
+ nine intervals, 50 ms), that frame builds nothing. With fewer samples the
128
+ median uses those available, and the 50 ms floor applies with none. At most
129
+ three consecutive eligible frames are skipped; the fourth builds at least
130
+ one key. On frames that build, another key starts only while elapsed build
131
+ time is below `sliceMs`. A single model build/copy batch is indivisible and
132
+ can overrun the budget; no further key starts after that overrun. Explicit
133
+ `ensureActorModel`, unsafe-consumer promotion and signature rebuilds remain
134
+ synchronous, bypassing horizon and pacing. Waiters acquire
135
+ no shared-build users until filled; removal, rebuild, scene load/swap,
136
+ resident-scene parking and disposal cancel their waits.
137
+
138
+ `world.loadQueue` is a read-only summary `{ pending, near, built, firstKeys,
139
+ deferredKeys }`, counting distinct model keys: pending now, pending inside
140
+ the current horizon, ready so far, ready in the first sync, and ever queued
141
+ respectively. With horizon 0, `near === pending`. Cancellation can
142
+ therefore leave `built < firstKeys + deferredKeys`. The player's `onStage`
143
+ receives `load:first-built` at the end of the first sync and
144
+ `load:rest-built` when the queue empties, with that summary as its second
145
+ argument. Rest-built means construction finished after a draw; the next
146
+ frame shows those last models, and deferred look baking may still remain.
147
+ Horizon-excluded keys are still pending, so `near === 0` alone never emits
148
+ rest-built. Bounds consumers must invalidate cached bounds when a rig fills;
149
+ the hub's distance-tier cache does this via the `modelfilled` listener above.
@@ -0,0 +1,114 @@
1
+ # Scene key: engine.look
2
+
3
+ The physics-3d kit's CLAUDE.md Quick reference points here. The key sits in
4
+ the `engine` object at a scene file's top level, beside `ground`.
5
+
6
+ - `"engine": { "look": { "bake": "deferred" } }` at the scene file's top
7
+ level (the same `engine` object) asks the engine to draw the scene's models
8
+ before their look is baked. Building a model bakes two things into it
9
+ (`engine3d/look.js`): its soft shading, by casting rays from every vertex
10
+ through a grid of the model's surfaces, and the attributes its outline is
11
+ pushed out by. That is most of what a model costs to build, and all of it
12
+ happens before the first frame: on a slow phone, several seconds of a
13
+ town's load. With the key a model is drawn at once without them, and they
14
+ are baked a little after each frame, nearest the camera first, about 6 ms a
15
+ frame. What a player sees: the scene appears sooner, flat-shaded where
16
+ parts meet and with no outlines, and over the first seconds the shading
17
+ and the outlines come in, model by model. The terms:
18
+ > With the key absent, a model is built exactly as before: the same code,
19
+ > baked before `syncActors` returns. With the key present, a model is built
20
+ > in the same shape, with the same meshes, materials and shader programs
21
+ > (nothing is recompiled when the baking lands), its occlusion all 1
22
+ > (nothing occludes it) and its outline hulls there and not drawn (their
23
+ > material's `visible` is off); once its baking has run, every attribute of
24
+ > every geometry holds what baking at once would have put there, and the
25
+ > hulls are drawn.
26
+
27
+ Any other value of `bake`, or none, is the key absent. It is read when the
28
+ scene loads (`runtime.bakesLookLater`), so it follows a scene switch, and
29
+ it applies to models `syncActors` builds while that scene plays, in the
30
+ play panel, a published deck and the scene editor alike; the model editor
31
+ and thumbnails build their own and always bake at once. A model already
32
+ baked (built for a scene without the key, or one whose baking has run) is
33
+ never unbaked. The other way round, a model built under the key and still
34
+ waiting when a scene without it places the same model in the same world is
35
+ the same shared build: it is drawn unbaked there too until its baking has
36
+ run, which goes on whichever scene plays. Whether a pass bakes later is
37
+ written on the world when `syncActors` starts (`world.bakesLookLater`), so
38
+ a `syncActors` for another runtime entered from inside a pass leaves its
39
+ own answer there for the rest of the outer one: models the outer pass
40
+ builds after it are baked as the inner runtime's scene asked. They end
41
+ the same either way.
42
+
43
+ It goes with `"dropEmptyParts": true`: that key takes the empty groups out
44
+ of a shared build after its look was applied and its baking queued, and the
45
+ baking was written down as geometries and matrices, so with both keys a
46
+ scene ends as it does with `dropEmptyParts` alone.
47
+
48
+ How it goes (`engine3d/lookbake.js` has the queue, the end of `look.js`
49
+ what is queued): one task per model built, cut into steps (the grid, each
50
+ surface marked into it, the rays of 128 vertices, a stretch of 384
51
+ vertices or triangle corners of a geometry's outline attributes, part by
52
+ part for merged parts). After each frame is drawn
53
+ (`renderWorld`), steps are started until 6 ms have gone; a step is never
54
+ interrupted, so a long one overruns and nothing starts after it that frame.
55
+ The frame the queue is first seen bakes nothing, so the first frame is on
56
+ screen first. Tasks are put nearest first whenever the queue has grown, by
57
+ the distance from the camera to the nearest actor placing the model as
58
+ things stood then; they are not re-sorted as the player walks. A task
59
+ bakes from what was written down when the model was built (each surface's
60
+ geometry and where it stood), so a model moved or animated since bakes the
61
+ same. Models sharing a parsed model file share one bake, as before, and a
62
+ geometry is baked once however many copies draw it.
63
+
64
+ `scene.three.lookBake` is null in a world that never built a model under
65
+ the key; otherwise it is the queue: `shown` (true once a frame has been
66
+ drawn with nothing left to bake, false again from the moment a model is
67
+ queued), `pending` (models still to bake), `ms` (time spent baking),
68
+ `baked` and `dropped` (tasks that ran to the end and left the whole of the
69
+ baking in every geometry not disposed, and tasks that did not: the model
70
+ went first, or a geometry was left that could not be written to), and
71
+ `budgetMs`, which a deck may set. **A harness, a screenshot or
72
+ a cover waits for `lookBake === null || lookBake.shown`, not for `pending`
73
+ to reach 0**: the baking is done after the frame is drawn, so the frame
74
+ that brings `pending` to 0 was drawn without the last of it, and it is the
75
+ next one that is the complete picture. A model released, rebuilt (its
76
+ file, its art or the look switch changed) or disposed with its world before
77
+ its task ran is dropped: the task listens for its geometries' `dispose` and
78
+ never writes to one that has been disposed.
79
+
80
+ A geometry replaced while it waits: a copy made with `geometry.clone()`
81
+ waits with the geometry it was copied from, and is given the same occlusion
82
+ and outline attributes when the task runs (in arrays of its own, as a copy
83
+ of a baked geometry has), so a mesh and its outline hull given the copy,
84
+ the first geometry disposed, end as they would in a scene without the key.
85
+ That holds whenever the copy is made (before the task begins or part way
86
+ through it) and whatever it is made from (the geometry, a copy, or either
87
+ one disposed and never written): a task counted in `baked` left every
88
+ geometry of its model that is not disposed, copies included, fully baked.
89
+ The engine does this itself for a part that glows. While it waits a
90
+ geometry has a `clone` of its own for this; it goes when the task ends, and
91
+ a `clone` kept hold of and called afterwards is the ordinary one.
92
+ Anything else put in a waiting geometry's place (a geometry built
93
+ separately, `copy()` into another one, or a copy whose vertices were then
94
+ replaced by a different number) is not written to: it keeps the occlusion
95
+ it came with, and an outline hull drawn from it has no outline attributes.
96
+ A task that ends with such a copy not disposed counts in `dropped`.
97
+ When the waiting geometry and every copy of it are gone before the task
98
+ runs, the hull's material is left not `visible`, so that hull has no
99
+ outline rather than a wrong one; a deck that swaps in its own geometry
100
+ under the key bakes it itself (`addOutlineAttributes`, engine3d/look.js)
101
+ and shows the hull. And a waiting geometry disposed while a mesh still
102
+ draws it is never baked, where without the key it would already have been.
103
+
104
+ `scripts/test-look-bake.mjs` holds all of it, and holds what a build
105
+ without the key gives to a number (`BAKED_AT_ONCE`, a digest from
106
+ `scripts/look-baseline.mjs` of every kit model built at once): change it
107
+ only in a commit that means to change what the look bakes into a model.
108
+
109
+ Do not set it if deck code reads `lookOcclusion`, `lookOutlineNormal` or
110
+ `lookOutlineReach`, or sets `visible` on an outline hull's material, in the
111
+ first seconds of a scene; and a screenshot or cover taken before
112
+ `lookBake.shown` is true shows the unbaked picture. Opt in when a
113
+ scene is many models and the load on a slow phone matters more than the
114
+ first seconds' polish; a small scene gains nothing.