castle-web-cli 0.4.231 → 0.4.233

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (368) hide show
  1. package/dist/agent-failures.d.ts +8 -0
  2. package/dist/agent-failures.js +19 -2
  3. package/dist/agent-prompts.d.ts +1 -1
  4. package/dist/agent-prompts.js +10 -3
  5. package/dist/agent.d.ts +64 -3
  6. package/dist/agent.js +170 -81
  7. package/dist/castle-host/host.d.ts +1 -0
  8. package/dist/castle-host/host.js +51 -3
  9. package/dist/castleJson.d.ts +4 -2
  10. package/dist/castleJson.js +2 -0
  11. package/dist/check.d.ts +3 -1
  12. package/dist/check.js +11 -1
  13. package/dist/devSessionStorage.js +47 -1
  14. package/dist/importPinMismatch.d.ts +22 -0
  15. package/dist/importPinMismatch.js +77 -0
  16. package/dist/importRegression.js +3 -15
  17. package/dist/imports.d.ts +10 -3
  18. package/dist/imports.js +88 -20
  19. package/dist/index.js +5 -4
  20. package/dist/init.js +1 -1
  21. package/dist/platformDoc.js +22 -0
  22. package/dist/routerFences.d.ts +5 -0
  23. package/dist/routerFences.js +12 -2
  24. package/dist/save-deck.d.ts +5 -0
  25. package/dist/save-deck.js +37 -4
  26. package/dist/serve.js +3 -0
  27. package/dist/serverBundle.js +5 -3
  28. package/dist/shell/assets/{index-D2tWM896.js → index-BjOxR-lW.js} +4 -4
  29. package/dist/shell/assets/index-MVLfNYd9.css +1 -0
  30. package/dist/shell/index.html +2 -2
  31. package/dist/taskSteer.d.ts +13 -0
  32. package/dist/taskSteer.js +22 -2
  33. package/kits/base/castle.json +1 -1
  34. package/kits/base/package-lock.json +1 -1
  35. package/kits/base/sdk/README.md +79 -2
  36. package/kits/base/sdk/avatar.d.ts +6 -2
  37. package/kits/base/sdk/avatar.js +12 -4
  38. package/kits/base/sdk/castle.d.ts +1 -1
  39. package/kits/base/sdk/commands.d.ts +14 -0
  40. package/kits/base/sdk/hub.d.ts +6 -2
  41. package/kits/base/sdk/hub.js +13 -0
  42. package/kits/base/sdk/multiplayer.js +17 -1
  43. package/kits/base/sdk/save.js +2 -1
  44. package/kits/base/sdk/server/hub.d.ts +87 -0
  45. package/kits/base/sdk/server/hub.js +70 -0
  46. package/kits/base/sdk/server/platformHandle.d.ts +31 -1
  47. package/kits/base/sdk/server/storage.d.ts +13 -0
  48. package/kits/base/sdk/server/storage.js +46 -0
  49. package/kits/base/sdk/server/wrapper.d.ts +36 -5
  50. package/kits/base/sdk/server/wrapper.js +83 -8
  51. package/kits/hub-game/CLAUDE.md +352 -12
  52. package/kits/hub-game/blueprints/avatar-10.scene +28 -0
  53. package/kits/hub-game/blueprints/avatar-11.scene +28 -0
  54. package/kits/hub-game/blueprints/avatar-12.scene +28 -0
  55. package/kits/hub-game/blueprints/avatar-13.scene +28 -0
  56. package/kits/hub-game/blueprints/avatar-14.scene +28 -0
  57. package/kits/hub-game/blueprints/avatar-15.scene +28 -0
  58. package/kits/hub-game/blueprints/avatar-4.scene +28 -0
  59. package/kits/hub-game/blueprints/avatar-5.scene +28 -0
  60. package/kits/hub-game/blueprints/avatar-6.scene +28 -0
  61. package/kits/hub-game/blueprints/avatar-7.scene +28 -0
  62. package/kits/hub-game/blueprints/avatar-8.scene +28 -0
  63. package/kits/hub-game/blueprints/avatar-9.scene +28 -0
  64. package/kits/hub-game/code/client/actorBudget.js +47 -0
  65. package/kits/hub-game/code/client/attention.js +11 -2
  66. package/kits/hub-game/code/client/avatar.js +345 -32
  67. package/kits/hub-game/code/client/avatarCap.js +228 -0
  68. package/kits/hub-game/code/client/avatarColors.js +70 -0
  69. package/kits/hub-game/code/client/avatarFaces.js +21 -0
  70. package/kits/hub-game/code/client/avatarShare.js +251 -0
  71. package/kits/hub-game/code/client/ballot.js +467 -0
  72. package/kits/hub-game/code/client/build.js +22 -0
  73. package/kits/hub-game/code/client/chat.js +12 -0
  74. package/kits/hub-game/code/client/chrome.js +1334 -50
  75. package/kits/hub-game/code/client/companion.js +716 -0
  76. package/kits/hub-game/code/client/companionDress.js +99 -0
  77. package/kits/hub-game/code/client/decor.js +509 -0
  78. package/kits/hub-game/code/client/earned.js +131 -0
  79. package/kits/hub-game/code/client/emoteBubble.js +75 -0
  80. package/kits/hub-game/code/client/grab.js +363 -20
  81. package/kits/hub-game/code/client/hats.js +26 -0
  82. package/kits/hub-game/code/client/hookLayer.js +328 -15
  83. package/kits/hub-game/code/client/hudClear.js +126 -0
  84. package/kits/hub-game/code/client/idle.js +163 -22
  85. package/kits/hub-game/code/client/interestCap.js +81 -0
  86. package/kits/hub-game/code/client/keys.js +36 -0
  87. package/kits/hub-game/code/client/labelsNear.js +205 -0
  88. package/kits/hub-game/code/client/menuIcons.js +34 -0
  89. package/kits/hub-game/code/client/pack.js +6 -2
  90. package/kits/hub-game/code/client/packFormat.js +3 -3
  91. package/kits/hub-game/code/client/rehello.js +167 -0
  92. package/kits/hub-game/code/client/shot.js +92 -0
  93. package/kits/hub-game/code/client/sound.js +63 -8
  94. package/kits/hub-game/code/client/soundscape.js +1151 -0
  95. package/kits/hub-game/code/client/soundscapeActions.js +99 -0
  96. package/kits/hub-game/code/client/soundscapeAmbience.js +453 -0
  97. package/kits/hub-game/code/client/soundscapeBaked.js +143 -0
  98. package/kits/hub-game/code/client/soundscapeBusker.js +217 -0
  99. package/kits/hub-game/code/client/soundscapeCourt.js +200 -0
  100. package/kits/hub-game/code/client/soundscapeCrowd.js +331 -0
  101. package/kits/hub-game/code/client/soundscapeCues.js +362 -0
  102. package/kits/hub-game/code/client/soundscapeMap.js +181 -0
  103. package/kits/hub-game/code/client/soundscapeMarket.js +176 -0
  104. package/kits/hub-game/code/client/soundscapeMusic.js +126 -0
  105. package/kits/hub-game/code/client/soundscapeMusicEngine.js +460 -0
  106. package/kits/hub-game/code/client/soundscapeSimlish.js +737 -0
  107. package/kits/hub-game/code/client/soundscapeSongs.js +127 -0
  108. package/kits/hub-game/code/client/soundscapeSongsRound3.js +63 -0
  109. package/kits/hub-game/code/client/soundscapeSynthesis.js +168 -0
  110. package/kits/hub-game/code/client/soundscapeUi.js +211 -0
  111. package/kits/hub-game/code/client/soundscapeVoice.js +1209 -0
  112. package/kits/hub-game/code/client/soundscapeWaves.js +206 -0
  113. package/kits/hub-game/code/client/spin.js +101 -0
  114. package/kits/hub-game/code/client/state.js +131 -1
  115. package/kits/hub-game/code/client/stuck.js +259 -0
  116. package/kits/hub-game/code/client/talk.js +538 -47
  117. package/kits/hub-game/code/client/tiers.js +541 -27
  118. package/kits/hub-game/code/client/toastBand.js +37 -0
  119. package/kits/hub-game/code/client/together.js +98 -1
  120. package/kits/hub-game/code/client/visibility.js +43 -0
  121. package/kits/hub-game/code/client/wear.js +470 -97
  122. package/kits/hub-game/code/client/yours.js +199 -0
  123. package/kits/hub-game/code/companionSpec.js +45 -0
  124. package/kits/hub-game/code/privateText.js +7 -0
  125. package/kits/hub-game/code/server/actions.js +133 -0
  126. package/kits/hub-game/code/server/actors.js +14 -1
  127. package/kits/hub-game/code/server/ask.js +155 -0
  128. package/kits/hub-game/code/server/ballot.js +539 -0
  129. package/kits/hub-game/code/server/cells.js +100 -0
  130. package/kits/hub-game/code/server/companion.js +82 -0
  131. package/kits/hub-game/code/server/cues.js +70 -0
  132. package/kits/hub-game/code/server/decor.js +269 -0
  133. package/kits/hub-game/code/server/earned.js +461 -0
  134. package/kits/hub-game/code/server/friendBests.js +166 -0
  135. package/kits/hub-game/code/server/friendsAmong.js +232 -0
  136. package/kits/hub-game/code/server/grab.js +296 -11
  137. package/kits/hub-game/code/server/history.js +5 -0
  138. package/kits/hub-game/code/server/hub.js +1317 -52
  139. package/kits/hub-game/code/server/idle.js +30 -11
  140. package/kits/hub-game/code/server/index.js +2 -2
  141. package/kits/hub-game/code/server/labels.js +28 -2
  142. package/kits/hub-game/code/server/manifest.js +424 -8
  143. package/kits/hub-game/code/server/menu.js +133 -0
  144. package/kits/hub-game/code/server/npcs.js +830 -80
  145. package/kits/hub-game/code/server/party.js +13 -2
  146. package/kits/hub-game/code/server/players.js +22 -0
  147. package/kits/hub-game/code/server/say.js +8 -2
  148. package/kits/hub-game/code/server/shot.js +110 -0
  149. package/kits/hub-game/code/server/standing.js +124 -0
  150. package/kits/hub-game/code/server/vis.js +113 -0
  151. package/kits/hub-game/code/server/wear.js +128 -11
  152. package/kits/hub-game/code/server/yours.js +59 -0
  153. package/kits/hub-game/code/shared/cues.js +9 -0
  154. package/kits/hub-game/code/shared/decor.js +41 -0
  155. package/kits/hub-game/code/shared/shot.js +19 -0
  156. package/kits/hub-game/code/shared/spin.js +57 -0
  157. package/kits/hub-game/code/systems/hub.js +1083 -85
  158. package/kits/hub-game/docs/content-pack.md +1 -1
  159. package/kits/hub-game/docs/contract.md +2440 -61
  160. package/kits/hub-game/docs/home-pieces.md +64 -0
  161. package/kits/hub-game/models/avatar-10.pxmodel +28 -0
  162. package/kits/hub-game/models/avatar-11.pxmodel +28 -0
  163. package/kits/hub-game/models/avatar-12.pxmodel +27 -0
  164. package/kits/hub-game/models/avatar-13.pxmodel +24 -0
  165. package/kits/hub-game/models/avatar-14.pxmodel +29 -0
  166. package/kits/hub-game/models/avatar-15.pxmodel +24 -0
  167. package/kits/hub-game/models/avatar-4.pxmodel +29 -0
  168. package/kits/hub-game/models/avatar-5.pxmodel +27 -0
  169. package/kits/hub-game/models/avatar-6.pxmodel +26 -0
  170. package/kits/hub-game/models/avatar-7.pxmodel +25 -0
  171. package/kits/hub-game/models/avatar-8.pxmodel +24 -0
  172. package/kits/hub-game/models/avatar-9.pxmodel +30 -0
  173. package/kits/hub-game/models/earned/badge-round.pxmodel +100 -0
  174. package/kits/hub-game/models/earned/badge-shield.pxmodel +117 -0
  175. package/kits/hub-game/models/earned/badge-star.pxmodel +87 -0
  176. package/kits/hub-game/models/earned/belt-plain.pxmodel +72 -0
  177. package/kits/hub-game/models/earned/held-ball.pxmodel +43 -0
  178. package/kits/hub-game/models/earned/held-lantern.pxmodel +85 -0
  179. package/kits/hub-game/models/earned/held-net.pxmodel +57 -0
  180. package/kits/hub-game/models/earned/held-trophy.pxmodel +109 -0
  181. package/kits/hub-game/models/earned/pin-round.pxmodel +62 -0
  182. package/kits/hub-game/models/earned/sash-plain.pxmodel +66 -0
  183. package/kits/hub-game/models/earned/square/belt-plain.pxmodel +104 -0
  184. package/kits/hub-game/models/earned/square/sash-plain.pxmodel +98 -0
  185. package/kits/hub-game/models/hats/bat-clip.pxmodel +206 -0
  186. package/kits/hub-game/models/hats/beekeeper.pxmodel +149 -0
  187. package/kits/hub-game/models/hats/cap.pxmodel +162 -0
  188. package/kits/hub-game/models/hats/captain.pxmodel +178 -0
  189. package/kits/hub-game/models/hats/crooked-top.pxmodel +172 -0
  190. package/kits/hub-game/models/hats/flower-crown.pxmodel +451 -0
  191. package/kits/hub-game/models/hats/foam-crown.pxmodel +179 -0
  192. package/kits/hub-game/models/hats/lantern.pxmodel +230 -0
  193. package/kits/hub-game/models/hats/laurel.pxmodel +533 -0
  194. package/kits/hub-game/models/hats/lighthouse.pxmodel +96 -0
  195. package/kits/hub-game/models/hats/sailor.pxmodel +141 -0
  196. package/kits/hub-game/models/hats/souwester.pxmodel +131 -0
  197. package/kits/hub-game/models/hats/straw.pxmodel +139 -0
  198. package/kits/hub-game/models/hats/sunflower.pxmodel +406 -0
  199. package/kits/hub-game/models/hats/sweatband.pxmodel +112 -0
  200. package/kits/hub-game/models/hats/witch.pxmodel +147 -0
  201. package/kits/hub-game/package-lock.json +2 -0
  202. package/kits/hub-game/package.json +2 -1
  203. package/kits/hub-game/scripts/check.mjs +78 -11
  204. package/kits/hub-game/scripts/companion-follower-wire.json +1 -0
  205. package/kits/hub-game/scripts/fixtures/decor-keyless-draw.json +121 -0
  206. package/kits/hub-game/scripts/fixtures/decor-keyless.json +293 -0
  207. package/kits/hub-game/scripts/fixtures/engine-models-stub.mjs +23 -0
  208. package/kits/hub-game/scripts/fixtures/fake-dom.mjs +107 -0
  209. package/kits/hub-game/scripts/fixtures/interest-legacy.json +385 -0
  210. package/kits/hub-game/scripts/fixtures/npc-notes-v1.77.jsonl +4 -0
  211. package/kits/hub-game/scripts/fixtures/vis-shared-wire.json +1 -0
  212. package/kits/hub-game/scripts/gen-avatars.mjs +933 -16
  213. package/kits/hub-game/scripts/gen-earned.mjs +285 -0
  214. package/kits/hub-game/scripts/gen-hats.mjs +827 -0
  215. package/kits/hub-game/scripts/grab.before-orbit.mjs +400 -0
  216. package/kits/hub-game/scripts/soundscape-wave-analysis.mjs +125 -0
  217. package/kits/hub-game/scripts/test-actions-client.mjs +488 -0
  218. package/kits/hub-game/scripts/test-actions.mjs +298 -0
  219. package/kits/hub-game/scripts/test-actor-budget.mjs +44 -0
  220. package/kits/hub-game/scripts/test-actors.mjs +19 -17
  221. package/kits/hub-game/scripts/test-ask-client.mjs +358 -0
  222. package/kits/hub-game/scripts/test-ask.mjs +269 -0
  223. package/kits/hub-game/scripts/test-attention.mjs +10 -1
  224. package/kits/hub-game/scripts/test-avatar-cap.mjs +379 -0
  225. package/kits/hub-game/scripts/test-avatar-colors.mjs +72 -0
  226. package/kits/hub-game/scripts/test-avatar-models.mjs +181 -0
  227. package/kits/hub-game/scripts/test-avatar-share.mjs +318 -0
  228. package/kits/hub-game/scripts/test-avatar-wire.mjs +753 -0
  229. package/kits/hub-game/scripts/test-avatar.mjs +540 -7
  230. package/kits/hub-game/scripts/test-ballot.mjs +1001 -0
  231. package/kits/hub-game/scripts/test-build.mjs +31 -0
  232. package/kits/hub-game/scripts/test-cells.mjs +71 -0
  233. package/kits/hub-game/scripts/test-chat.mjs +694 -0
  234. package/kits/hub-game/scripts/test-classic.mjs +2 -0
  235. package/kits/hub-game/scripts/test-companion-chat.mjs +198 -0
  236. package/kits/hub-game/scripts/test-companion-client.mjs +1167 -0
  237. package/kits/hub-game/scripts/test-companion.mjs +259 -0
  238. package/kits/hub-game/scripts/test-decor-client.mjs +303 -0
  239. package/kits/hub-game/scripts/test-decor.mjs +457 -0
  240. package/kits/hub-game/scripts/test-earned-client.mjs +459 -0
  241. package/kits/hub-game/scripts/test-earned.mjs +1194 -0
  242. package/kits/hub-game/scripts/test-emote-bubble.mjs +110 -0
  243. package/kits/hub-game/scripts/test-friend-bests.mjs +435 -0
  244. package/kits/hub-game/scripts/test-grab-client.mjs +186 -3
  245. package/kits/hub-game/scripts/test-grab-orbit.mjs +918 -0
  246. package/kits/hub-game/scripts/test-grab.mjs +864 -3
  247. package/kits/hub-game/scripts/test-hats.mjs +483 -0
  248. package/kits/hub-game/scripts/test-hub-leaving.mjs +203 -0
  249. package/kits/hub-game/scripts/test-hub-ops.mjs +439 -2
  250. package/kits/hub-game/scripts/test-hub-trip.mjs +1228 -1
  251. package/kits/hub-game/scripts/test-hud-clear.mjs +1000 -0
  252. package/kits/hub-game/scripts/test-idle.mjs +361 -1
  253. package/kits/hub-game/scripts/test-interest-cap.mjs +36 -0
  254. package/kits/hub-game/scripts/test-interest-cells.mjs +493 -0
  255. package/kits/hub-game/scripts/test-interest-client.mjs +118 -0
  256. package/kits/hub-game/scripts/test-keys.mjs +46 -1
  257. package/kits/hub-game/scripts/test-labels.mjs +596 -0
  258. package/kits/hub-game/scripts/test-manifest.mjs +282 -0
  259. package/kits/hub-game/scripts/test-menu-client.mjs +480 -0
  260. package/kits/hub-game/scripts/test-menu.mjs +296 -0
  261. package/kits/hub-game/scripts/test-npcs.mjs +1718 -12
  262. package/kits/hub-game/scripts/test-object-entry.mjs +76 -0
  263. package/kits/hub-game/scripts/test-pack.mjs +7 -0
  264. package/kits/hub-game/scripts/test-party.mjs +22 -1
  265. package/kits/hub-game/scripts/test-picker.mjs +314 -0
  266. package/kits/hub-game/scripts/test-rehello.mjs +1039 -0
  267. package/kits/hub-game/scripts/test-relations-among.mjs +222 -0
  268. package/kits/hub-game/scripts/test-relations-refresh.mjs +188 -0
  269. package/kits/hub-game/scripts/test-say.mjs +59 -2
  270. package/kits/hub-game/scripts/test-shot.mjs +756 -0
  271. package/kits/hub-game/scripts/test-soundscape.mjs +5432 -0
  272. package/kits/hub-game/scripts/test-spin.mjs +314 -0
  273. package/kits/hub-game/scripts/test-standing.mjs +416 -0
  274. package/kits/hub-game/scripts/test-stuck.mjs +1903 -0
  275. package/kits/hub-game/scripts/test-tier-cells.mjs +706 -0
  276. package/kits/hub-game/scripts/test-tiers-render.mjs +339 -0
  277. package/kits/hub-game/scripts/test-tiers.mjs +666 -3
  278. package/kits/hub-game/scripts/test-toast-band.mjs +61 -0
  279. package/kits/hub-game/scripts/test-try-on.mjs +940 -0
  280. package/kits/hub-game/scripts/test-vis.mjs +343 -0
  281. package/kits/hub-game/scripts/test-visibility.mjs +134 -0
  282. package/kits/hub-game/scripts/test-yours-chrome.mjs +166 -0
  283. package/kits/hub-game/scripts/test-yours.mjs +372 -0
  284. package/kits/multiplayer-3d/CLAUDE.md +50 -0
  285. package/kits/multiplayer-3d/castle.json +5 -5
  286. package/kits/multiplayer-3d/code/client/avatars.js +7 -0
  287. package/kits/multiplayer-3d/code/client/gait.js +65 -0
  288. package/kits/multiplayer-3d/code/client/nameTags.js +59 -4
  289. package/kits/multiplayer-3d/code/options.js +5 -0
  290. package/kits/multiplayer-3d/code/server/ownership.js +10 -2
  291. package/kits/multiplayer-3d/code/server/sceneBodies.js +12 -0
  292. package/kits/multiplayer-3d/code/server/world.js +7 -0
  293. package/kits/multiplayer-3d/code/systems/multiplayer.js +74 -4
  294. package/kits/multiplayer-3d/package.json +2 -1
  295. package/kits/multiplayer-3d/scripts/fixtures/README.md +11 -0
  296. package/kits/multiplayer-3d/scripts/fixtures/ownership-legacy.json +2 -0
  297. package/kits/multiplayer-3d/scripts/ownership-harness.mjs +102 -0
  298. package/kits/multiplayer-3d/scripts/ownership-loader.mjs +46 -0
  299. package/kits/multiplayer-3d/scripts/ownership-worker.mjs +15 -0
  300. package/kits/multiplayer-3d/scripts/record-ownership-session.mjs +98 -0
  301. package/kits/multiplayer-3d/scripts/test-eligible-claims.mjs +167 -0
  302. package/kits/multiplayer-3d/scripts/test-own-name-tag.mjs +247 -0
  303. package/kits/physics-2d/CLAUDE.md +9 -0
  304. package/kits/physics-2d/castle.json +2 -2
  305. package/kits/physics-2d/engine/scene.js +288 -1
  306. package/kits/physics-2d/engine/skyKey.js +129 -0
  307. package/kits/physics-2d/engine/stillClock.js +106 -0
  308. package/kits/physics-2d/engine/updateBudget.js +21 -0
  309. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +370 -1
  310. package/kits/physics-3d/CLAUDE.md +1391 -0
  311. package/kits/physics-3d/behaviors/Player.jsx +921 -3
  312. package/kits/physics-3d/castle.json +3 -3
  313. package/kits/physics-3d/docs/pxmodel-format.md +12 -0
  314. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +98 -10
  315. package/kits/physics-3d/engine3d/actornode.js +86 -0
  316. package/kits/physics-3d/engine3d/animationBudget.js +23 -0
  317. package/kits/physics-3d/engine3d/editorWorld.js +6 -0
  318. package/kits/physics-3d/engine3d/emptynodes.js +232 -0
  319. package/kits/physics-3d/engine3d/framecap.js +96 -0
  320. package/kits/physics-3d/engine3d/gait.js +118 -0
  321. package/kits/physics-3d/engine3d/kithooks.js +47 -0
  322. package/kits/physics-3d/engine3d/look.js +507 -48
  323. package/kits/physics-3d/engine3d/lookbake.js +208 -0
  324. package/kits/physics-3d/engine3d/materialpresets.js +2 -0
  325. package/kits/physics-3d/engine3d/motion.js +39 -10
  326. package/kits/physics-3d/engine3d/nearshadows.js +37 -19
  327. package/kits/physics-3d/engine3d/optimize.js +58 -5
  328. package/kits/physics-3d/engine3d/orbitinput.js +755 -0
  329. package/kits/physics-3d/engine3d/orbitlens.js +48 -0
  330. package/kits/physics-3d/engine3d/ownmodel.js +213 -0
  331. package/kits/physics-3d/engine3d/pxmodel.js +42 -11
  332. package/kits/physics-3d/engine3d/shadowfade.js +882 -0
  333. package/kits/physics-3d/engine3d/sky.js +547 -0
  334. package/kits/physics-3d/engine3d/skylife.js +306 -0
  335. package/kits/physics-3d/engine3d/unchanged.js +11 -0
  336. package/kits/physics-3d/engine3d/viewrange.js +52 -0
  337. package/kits/physics-3d/engine3d/world3d.js +870 -87
  338. package/kits/physics-3d/main.jsx +5 -0
  339. package/kits/physics-3d/package.json +1 -1
  340. package/kits/physics-3d/scripts/Player.before-orbit.mjs +310 -0
  341. package/kits/physics-3d/scripts/Scene3DPlayer.before-orbit.jsx +337 -0
  342. package/kits/physics-3d/scripts/look-baseline.mjs +155 -0
  343. package/kits/physics-3d/scripts/test-camera-follow.mjs +12 -2
  344. package/kits/physics-3d/scripts/test-camera-orbit.mjs +4588 -0
  345. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +787 -0
  346. package/kits/physics-3d/scripts/test-frame-cap-bob.mjs +435 -0
  347. package/kits/physics-3d/scripts/test-frame-cap.mjs +452 -0
  348. package/kits/physics-3d/scripts/test-gait.mjs +387 -0
  349. package/kits/physics-3d/scripts/test-look-bake.mjs +1056 -0
  350. package/kits/physics-3d/scripts/test-model-parse-cache.mjs +92 -0
  351. package/kits/physics-3d/scripts/test-near-shadows.mjs +3 -0
  352. package/kits/physics-3d/scripts/test-orbit-shadow-fade.mjs +1920 -0
  353. package/kits/physics-3d/scripts/test-orbit-shift-lock.mjs +545 -0
  354. package/kits/physics-3d/scripts/test-orbit-shot.mjs +583 -0
  355. package/kits/physics-3d/scripts/test-orbit-view.mjs +230 -0
  356. package/kits/physics-3d/scripts/test-skip-empty-nodes.mjs +845 -0
  357. package/kits/physics-3d/scripts/test-sky.mjs +2470 -0
  358. package/kits/physics-3d/scripts/test-static-actors.mjs +13 -1
  359. package/kits/physics-3d/scripts/test-static-passes.mjs +1 -1
  360. package/kits/physics-3d/scripts/test-static-scenery.mjs +2171 -0
  361. package/kits/physics-3d/scripts/test-steady-hover.mjs +635 -0
  362. package/kits/physics-3d/scripts/test-view-range.mjs +260 -0
  363. package/kits/physics-3d/systems/physics3d.js +474 -12
  364. package/kits/real-time/castle.json +2 -2
  365. package/kits/real-time/code/server/gameHooks.js +7 -0
  366. package/kits/real-time/code/server/session.js +97 -19
  367. package/package.json +2 -2
  368. package/dist/shell/assets/index-Cf61cNfT.css +0 -1
@@ -0,0 +1,716 @@
1
+ // The companion (v1.71): private follower, public shoulder glows; no actors.
2
+ import * as THREE from 'three';
3
+ import { check } from '../companionSpec.js';
4
+ import { paperSpecies, dressBird } from './companionDress.js';
5
+ import { orbitFov } from '@imports/castle.physics-3d/engine3d/orbitlens.js';
6
+
7
+ // As wear.js: the avatar origin is the capsule centre, feet 0.7 m below it.
8
+ // The companion floats 1.45 m over those feet on every avatar.
9
+ const HEIGHT = -0.7 + 1.45;
10
+ export const LEASH = 10;
11
+ const distance = (a, b) => Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z);
12
+ export function sanitise(c) {
13
+ try {
14
+ return check(c);
15
+ } catch {
16
+ return null;
17
+ }
18
+ }
19
+ // yaw and t are radians and seconds, respectively; facing is +z at yaw 0.
20
+ // Pure motion history: a target or speed >= 0.2 m/s resets the still timer.
21
+ export function restStep(previous, player, dt, pointing = false) {
22
+ const elapsed = Math.max(0, dt);
23
+ const speed = previous && elapsed > 0 ? Math.hypot(player.x - previous.x, player.y - previous.y, player.z - previous.z) / elapsed : Infinity;
24
+ const still = !pointing && speed < 0.2 ? (previous?.still ?? 0) + elapsed : 0;
25
+ return { x: player.x, y: player.y, z: player.z, still, resting: still >= 1.5 };
26
+ }
27
+ export function followTarget(player, pointAt, t, resting = false) {
28
+ const yaw = player.yaw ?? 0;
29
+ if (resting && !pointAt) {
30
+ return { x: player.x + 0.28 * Math.cos(yaw), y: player.y - 0.7 + 1.25, z: player.z - 0.28 * Math.sin(yaw) };
31
+ }
32
+ let dx = 0.55 * Math.cos(yaw) - 0.35 * Math.sin(yaw);
33
+ let dz = -0.55 * Math.sin(yaw) - 0.35 * Math.cos(yaw);
34
+ if (pointAt) {
35
+ const x = pointAt.x - player.x, z = pointAt.z - player.z, d = Math.hypot(x, z);
36
+ if (d > 0) {
37
+ dx = 0.9 * x / d;
38
+ dz = 0.9 * z / d;
39
+ }
40
+ }
41
+ return { x: player.x + dx, y: player.y + HEIGHT + 0.06 * Math.sin(t * Math.PI), z: player.z + dz };
42
+ }
43
+ // Camera and projection are inputs so framing can be tested without a renderer.
44
+ export function frontTarget(player, camera, t, panel, view, project, reach = 1.3) {
45
+ const length = Math.hypot(camera?.forward?.x ?? 0, camera?.forward?.z ?? 0);
46
+ const dx = length > 0.0001 ? (camera?.forward?.x ?? 0) / length : Math.sin(player.yaw ?? 0);
47
+ const dz = length > 0.0001 ? (camera?.forward?.z ?? 0) / length : Math.cos(player.yaw ?? 0);
48
+ const target = { x: player.x + reach * dx, y: player.y - 0.7 + 1.55 + 0.04 * Math.sin(t * Math.PI), z: player.z + reach * dz };
49
+ const base = target.y;
50
+ // A far orbit or a tall panel can leave every lift covered: then the
51
+ // on-screen candidate highest above the panel wins, not the last one tried.
52
+ let best = null, bestY = Infinity;
53
+ for (let lift = 0; lift <= 10; lift++) {
54
+ const at = { x: player.x + reach * dx, y: base + lift * 0.2, z: player.z + reach * dz };
55
+ // Recheck after lifting: a raised target can otherwise enter the camera.
56
+ if (camera?.position && Math.hypot(at.x - camera.position.x, at.y - camera.position.y, at.z - camera.position.z) < 0.9) {
57
+ at.x += dx * 1.8;
58
+ at.z += dz * 1.8;
59
+ }
60
+ if (!project) {
61
+ best = at;
62
+ break;
63
+ }
64
+ const screen = project(at);
65
+ const onScreen = screen && screen.x >= 22 && screen.x <= view.w - 22 && screen.y >= 22 && screen.y <= view.h - 22;
66
+ if (onScreen && !(panel && screen.x >= panel.left - 22 && screen.x <= panel.right + 22 && screen.y >= panel.top - 22 && screen.y <= panel.bottom + 22)) {
67
+ best = at;
68
+ break;
69
+ }
70
+ if (onScreen && screen.y < bestY) {
71
+ best = at;
72
+ bestY = screen.y;
73
+ }
74
+ best ??= lift === 0 ? at : best;
75
+ }
76
+ Object.assign(target, best);
77
+ return { ...target, yaw: Math.atan2(player.x - target.x, player.z - target.z) };
78
+ }
79
+ export function chatTarget(player, camera, t, panel, view, project) {
80
+ return frontTarget(player, camera, t, panel, view, project);
81
+ }
82
+ function showAxes(camera) {
83
+ const forward = new THREE.Vector3(camera.forward.x, camera.forward.y ?? 0, camera.forward.z).normalize();
84
+ const right = new THREE.Vector3().crossVectors(forward, new THREE.Vector3(camera.up?.x ?? 0, camera.up?.y ?? 1, camera.up?.z ?? 0));
85
+ if (right.lengthSq() < 0.000001) { right.set(1, 0, 0); }
86
+ right.normalize();
87
+ return { forward, right, up: new THREE.Vector3().crossVectors(right, forward).normalize() };
88
+ }
89
+ // Camera sees the paper from the side and above, independent of orbit elevation.
90
+ // side/lift are camera-right/up displacements divided by forward depth.
91
+ export function showRotation(camera, t = 0, side = 0, lift = 0) {
92
+ const { forward, right, up } = showAxes(camera);
93
+ const yaw = (8 + 2 * Math.sin(t * Math.PI / 2)) * Math.PI / 180;
94
+ const basis = new THREE.Quaternion().setFromRotationMatrix(new THREE.Matrix4().makeBasis(right, up, forward.clone().negate()));
95
+ // Perspective projects up as (up.x - side * up.depth, up.y - lift * up.depth).
96
+ // Keep the existing pose where it meets the roll limit; otherwise bank only
97
+ // enough for 9 degrees, leaving a margin under 10. Turning about camera
98
+ // forward preserves the side/above angles and keeps the correction smooth.
99
+ const tilt = Math.PI / 6, limit = 9 * Math.PI / 180;
100
+ const roll = Math.atan2(side * Math.sin(tilt), Math.cos(tilt) + lift * Math.sin(tilt));
101
+ const slope = Math.sign(roll) * Math.tan(limit);
102
+ const bank = Math.abs(roll) <= limit ? 0 : Math.asin(THREE.MathUtils.clamp(
103
+ -Math.tan(tilt) * (side - slope * lift) / Math.hypot(1, slope), -1, 1)) + Math.atan(slope);
104
+ return basis.premultiply(new THREE.Quaternion().setFromAxisAngle(up, -yaw))
105
+ .premultiply(new THREE.Quaternion().setFromAxisAngle(right, Math.PI / 6))
106
+ .premultiply(new THREE.Quaternion().setFromAxisAngle(forward, bank));
107
+ }
108
+ const showWing = (t, flutter) => 1.2 + 0.08 * Math.sin(t * flutter * Math.PI);
109
+ function showOffsets(camera, vertices, t, side, lift) {
110
+ const { forward, right, up } = showAxes(camera);
111
+ const rotation = showRotation(camera, t, side, lift), axis = new THREE.Vector3(0, 0, 1);
112
+ return vertices.map((vertex) => {
113
+ const rotated = vertex.clone();
114
+ if (vertex.wing) { rotated.applyAxisAngle(axis, vertex.wing * showWing(t, vertex.flutter)); }
115
+ rotated.applyQuaternion(rotation);
116
+ return { x: rotated.dot(right), y: rotated.dot(up), z: rotated.dot(forward) };
117
+ });
118
+ }
119
+ function showBounds(offsets, depth, side, lift, tan, aspect) {
120
+ let left = Infinity, right = -Infinity, bottom = Infinity, top = -Infinity;
121
+ for (const offset of offsets) {
122
+ const x = (depth * side + offset.x) / ((depth + offset.z) * tan * aspect);
123
+ const y = (depth * lift + offset.y) / ((depth + offset.z) * tan);
124
+ left = Math.min(left, x); right = Math.max(right, x); bottom = Math.min(bottom, y); top = Math.max(top, y);
125
+ }
126
+ return { left, right, bottom, top };
127
+ }
128
+ function showInside(pos, player, camera, view, vertices, t) {
129
+ const { forward, right, up } = showAxes(camera);
130
+ const offset = new THREE.Vector3(pos.x - camera.position.x, pos.y - camera.position.y, pos.z - camera.position.z);
131
+ const depth = offset.dot(forward);
132
+ const side = offset.dot(right) / depth;
133
+ const lift = offset.dot(up) / depth;
134
+ const b = showBounds(showOffsets(camera, vertices, t, side, lift), depth, side, lift,
135
+ Math.tan(camera.fov * Math.PI / 360), view.w / view.h);
136
+ const playerOffset = new THREE.Vector3(player.x - camera.position.x, player.y - camera.position.y, player.z - camera.position.z);
137
+ const playerX = playerOffset.dot(right) / (playerOffset.dot(forward) * Math.tan(camera.fov * Math.PI / 360) * view.w / view.h);
138
+ const rightEdge = view.h > view.w ? Math.min(0.92, playerX - 0.04) : 0.92;
139
+ return b.left >= -0.92 && b.right <= rightEdge && b.bottom >= -0.92 && b.top <= 0.92;
140
+ }
141
+ // Fit paper and wear, excluding glow. Centre the projected box, not its origin:
142
+ // the hat and long beak make those two points noticeably different up close.
143
+ export function showTarget(player, camera, view, size, radius = 0, vertices = null, t = 0) {
144
+ const { forward, right, up } = showAxes(camera);
145
+ const tan = Math.tan(camera.fov * Math.PI / 360), aspect = view.w / view.h;
146
+ const portrait = view.h > view.w;
147
+ const centreX = portrait ? -0.46 : -0.3;
148
+ const centreY = portrait ? 0.2 : 0.1;
149
+ let side = centreX * tan * aspect, lift = centreY * tan;
150
+ const from = new THREE.Vector3(player.x - camera.position.x, player.y - camera.position.y, player.z - camera.position.z);
151
+ const minimum = Math.max(camera.near + 0.3, camera.near + 0.15 + radius);
152
+ let d, target;
153
+ const at = (depth) => new THREE.Vector3(camera.position.x, camera.position.y, camera.position.z)
154
+ .addScaledVector(forward, depth).addScaledVector(right, depth * side).addScaledVector(up, depth * lift);
155
+ for (let centre = 0; centre < (vertices ? 8 : 1); centre++) {
156
+ // Camera clearance takes priority if an extreme zoom leaves no room.
157
+ const maximum = Math.max(minimum, Math.min(from.dot(forward) - 0.4, (from.length() - 0.4) / Math.hypot(1, side, lift)));
158
+ d = Math.max(minimum, Math.min(maximum, size / (2 * tan * 0.33)));
159
+ if (vertices) {
160
+ const offsets = showOffsets(camera, vertices, t, side, lift);
161
+ const bounds = (depth) => showBounds(offsets, depth, side, lift, tan, aspect);
162
+ // Keep the whole box inside the inset and left of the player by 2%
163
+ // of view width in portrait; reduce height for a wider silhouette.
164
+ const playerX = from.dot(right) / (from.dot(forward) * tan * aspect);
165
+ const edge = view.h > view.w ? Math.min(0.919, playerX - 0.041) : 0.919;
166
+ const width = 2 * Math.min(centreX + 0.919, edge - centreX);
167
+ const fits = (depth) => {
168
+ const b = bounds(depth);
169
+ return b.top - b.bottom <= 0.66 && b.right - b.left <= width;
170
+ };
171
+ if (fits(minimum)) { d = minimum; }
172
+ else if (!fits(maximum)) { d = maximum; }
173
+ else {
174
+ let lo = minimum, hi = maximum;
175
+ for (let i = 0; i < 22; i++) {
176
+ const mid = (lo + hi) / 2;
177
+ if (fits(mid)) { hi = mid; } else { lo = mid; }
178
+ }
179
+ d = (lo + hi) / 2;
180
+ }
181
+ const b = bounds(d);
182
+ // Leave the last iteration's distance and centre paired exactly.
183
+ if (centre < 7) {
184
+ side += (centreX - (b.left + b.right) / 2) * tan * aspect;
185
+ lift += (centreY - (b.bottom + b.top) / 2) * tan;
186
+ }
187
+ }
188
+ target = at(d);
189
+ }
190
+ return { x: target.x, y: target.y, z: target.z, yaw: Math.atan2(camera.position.x - target.x, camera.position.z - target.z) };
191
+ }
192
+ // A held pose moves with the camera immediately; its remaining approach
193
+ // offset settles with a short spring in that moving camera frame.
194
+ function carryShow(pos, previous, camera) {
195
+ const old = showAxes(previous), next = showAxes(camera);
196
+ const offset = new THREE.Vector3(pos.x - previous.position.x, pos.y - previous.position.y, pos.z - previous.position.z);
197
+ return new THREE.Vector3(camera.position.x, camera.position.y, camera.position.z)
198
+ .addScaledVector(next.right, offset.dot(old.right)).addScaledVector(next.up, offset.dot(old.up)).addScaledVector(next.forward, offset.dot(old.forward));
199
+ }
200
+ function safeShow(pos, player, camera, radius) {
201
+ const { forward } = showAxes(camera);
202
+ const offset = new THREE.Vector3(pos.x - camera.position.x, pos.y - camera.position.y, pos.z - camera.position.z);
203
+ const playerOffset = new THREE.Vector3(player.x - camera.position.x, player.y - camera.position.y, player.z - camera.position.z);
204
+ const depth = offset.dot(forward), minimum = Math.max(camera.near + 0.3, camera.near + 0.15 + radius);
205
+ const maximum = Math.max(minimum, playerOffset.dot(forward) - 0.4);
206
+ const safeDepth = Math.max(minimum, Math.min(maximum, depth));
207
+ offset.addScaledVector(forward, safeDepth - depth);
208
+ // A far sideways approach can exceed the player distance even at safe depth.
209
+ const radial = Math.max(minimum, playerOffset.length() - 0.4);
210
+ const side = offset.clone().addScaledVector(forward, -safeDepth);
211
+ const room = Math.sqrt(Math.max(0, radial * radial - safeDepth * safeDepth));
212
+ if (side.length() > room) { side.setLength(room); offset.copy(side).addScaledVector(forward, safeDepth); }
213
+ return { x: camera.position.x + offset.x, y: camera.position.y + offset.y, z: camera.position.z + offset.z };
214
+ }
215
+ export function motionTarget(player, pointAt, t, resting, chat) {
216
+ return chat ? chatTarget(player, chat.camera, t, chat.panel, chat.view, chat.project) : followTarget(player, pointAt, t, resting);
217
+ }
218
+ export function leadTarget(player, pointAt, t) {
219
+ if (!pointAt || Math.hypot(pointAt.x - player.x, pointAt.z - player.z) > LEASH) { return null; }
220
+ const angle = t * Math.PI / 3;
221
+ return { x: pointAt.x + 0.35 * Math.cos(angle), y: (pointAt.y ?? 0) + 1.1 + 0.06 * Math.sin(t * Math.PI), z: pointAt.z + 0.35 * Math.sin(angle) };
222
+ }
223
+ const mix = (a, b, t) => ({ x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t, z: a.z + (b.z - a.z) * t });
224
+ const yawTo = (a, b) => Math.atan2(b.x - a.x, b.z - a.z);
225
+ const turnTo = (a, b, t) => a + Math.atan2(Math.sin(b - a), Math.cos(b - a)) * t;
226
+ const legSeconds = (a, b) => Math.min(4, distance(a, b) / 3);
227
+ // Pure route history; all time is injected. Consume leftover dt at phase
228
+ // boundaries so 30 Hz, 60 Hz and a single long frame follow the same route.
229
+ export function leadStep(previous, { id, player, pointAt, pos, yaw = 0, dt, now, framing, chatting = false }) {
230
+ const hover = leadTarget(player, pointAt, now / 1000);
231
+ if (!id || !hover || chatting || (previous?.id === id && distance(previous.player, player) > 6)) { return null; }
232
+ let s = previous;
233
+ if (!s || s.id !== id) {
234
+ const front = frontTarget(player, framing?.camera, 0, framing?.panel, framing?.view, framing?.project, 1.5);
235
+ const from = pos ?? followTarget(player, null, now / 1000);
236
+ s = { id, player: { ...player }, phase: 'front', elapsed: 0, from, front, goal: hover, pos: from, yaw, duration: legSeconds(from, front) };
237
+ } else {s = { ...s };}
238
+ let left = Math.max(0, dt);
239
+ while (s.phase !== 'hover') {
240
+ const used = Math.min(left, Math.max(0, s.duration - s.elapsed));
241
+ s.elapsed += used;
242
+ left -= used;
243
+ const progress = s.duration ? Math.min(1, s.elapsed / s.duration) : 1;
244
+ if (s.phase === 'front') {
245
+ s.pos = mix(s.from, s.front, progress);
246
+ s.yaw = progress < 1 ? yawTo(s.from, s.front) : s.front.yaw;
247
+ } else if (s.phase === 'pause') {
248
+ s.yaw = yawTo(s.pos, player);
249
+ s.front = { ...s.front, yaw: s.yaw };
250
+ } else if (s.phase === 'turn') {
251
+ s.yaw = turnTo(s.front.yaw, yawTo(s.front, s.goal), progress * progress * (3 - 2 * progress));
252
+ } else if (s.phase === 'fly') {
253
+ s.pos = mix(s.front, s.goal, progress);
254
+ s.yaw = yawTo(s.front, s.goal);
255
+ }
256
+ if (progress < 1) { break; }
257
+ s.elapsed = 0;
258
+ if (s.phase === 'front') { s.phase = 'pause'; s.duration = 0.6; }
259
+ else if (s.phase === 'pause') { s.phase = 'turn'; s.duration = 0.4; }
260
+ else if (s.phase === 'turn') { s.phase = 'fly'; s.duration = legSeconds(s.front, s.goal); }
261
+ else { s.phase = 'hover'; }
262
+ if (left <= 0) { break; }
263
+ }
264
+ if (s.phase === 'hover' && left > 0) {
265
+ s.pos = mix(s.pos, hover, Math.min(1, 3 * left / (distance(s.pos, hover) || 1)));
266
+ s.yaw = yawTo(s.pos, pointAt);
267
+ }
268
+ return s;
269
+ }
270
+ export const isHatStall = (actor) => Boolean(actor?.components?.TownHats);
271
+ // A hat finishes its short performance even if the visit ends on the way home.
272
+ export function hatStep(previous, id, now) {
273
+ let s = previous;
274
+ if (!s || (s.phase === 'done' && id !== s.id)) {s = id ? { id, since: now } : null;}
275
+ if (!s) { return null; }
276
+ const age = Math.max(0, (now - s.since) / 1000);
277
+ const drop = Math.max(0, age - 3);
278
+ return { ...s, phase: age < 3 ? 'on' : age < 3.6 ? 'drop' : 'done', drop, opacity: Math.max(0, 1 - drop / 0.6) };
279
+ }
280
+ // Private cues have no actor: the server sends them only to the earning player.
281
+ export const ownStamp = (msg) => msg?.cue === 'stamp' && !Object.hasOwn(msg, 'actor');
282
+ export function twirlStep(previous, stamps, now) {
283
+ const s = previous ?? { seen: 0, since: -Infinity };
284
+ const since = stamps > s.seen && now - s.since >= 10_000 ? now : s.since;
285
+ const age = (now - since) / 1000;
286
+ const active = age >= 0 && age < 1;
287
+ return { seen: stamps, since, active, yaw: active ? age * Math.PI * 2 : 0, hop: active ? Math.sin(age * Math.PI) * 0.25 : 0, pulse: active ? Math.sin(age * Math.PI) : 0 };
288
+ }
289
+ export const isQuiet = ({ at, line, busy, talking, hat, twirl }) => !at && !line && !busy && !talking && !hat && !twirl;
290
+
291
+ // Positive local X pitch lowers the +z beak (the group uses YXZ rotation).
292
+ export const lookDownPitch = (pos, target) => distance(pos, target) <= 0.6 ? 35 * Math.PI / 180 : 0;
293
+
294
+ // During a lead/return flight, measure drift from its whole route rather
295
+ // than its destination: a ten-metre flight must not trigger the six-metre snap.
296
+ export function step(pos, target, dt, flightFrom = null, flying = false) {
297
+ let expected = target;
298
+ if (pos && flightFrom) {
299
+ const dx = target.x - flightFrom.x, dy = target.y - flightFrom.y, dz = target.z - flightFrom.z;
300
+ const length2 = dx * dx + dy * dy + dz * dz;
301
+ const along = length2 ? Math.max(0, Math.min(1, ((pos.x - flightFrom.x) * dx + (pos.y - flightFrom.y) * dy + (pos.z - flightFrom.z) * dz) / length2)) : 0;
302
+ expected = { x: flightFrom.x + along * dx, y: flightFrom.y + along * dy, z: flightFrom.z + along * dz };
303
+ }
304
+ if (!pos || distance(pos, expected) > 6) {
305
+ return { ...target };
306
+ }
307
+ const a = 1 - Math.exp(-Math.max(0, dt) / (flying || flightFrom ? 0.5 : 0.25));
308
+ return { x: pos.x + (target.x - pos.x) * a, y: pos.y + (target.y - pos.y) * a, z: pos.z + (target.z - pos.z) * a };
309
+ }
310
+ export function quietStep(previous, quiet, dt) {
311
+ const a = 1 - Math.exp(-Math.max(0, dt) / 0.15);
312
+ const ease = (key, goal) => {
313
+ const value = (previous?.[key] ?? 1) + (goal - (previous?.[key] ?? 1)) * a;
314
+ return Math.abs(value - goal) < 0.02 ? goal : value;
315
+ };
316
+ return { scale: ease('scale', quiet ? 0.7 : 1), opacity: ease('opacity', quiet ? 0.5 : 1) };
317
+ }
318
+ export function appearance(root, state, show = false) {
319
+ root.scale.setScalar(root.userData.normalScale * state.scale);
320
+ root.traverse((node) => {
321
+ for (const material of node.material ? (Array.isArray(node.material) ? node.material : [node.material]) : []) {
322
+ const base = material.userData.companionBase ??= { opacity: material.opacity, transparent: material.transparent, depthWrite: material.depthWrite };
323
+ const opaque = show && material.blending !== THREE.AdditiveBlending;
324
+ const transparent = !opaque && (state.opacity < 1 || base.transparent);
325
+ if (material.transparent !== transparent) {
326
+ material.transparent = transparent;
327
+ material.needsUpdate = true;
328
+ }
329
+ material.opacity = opaque ? 1 : base.opacity * state.opacity;
330
+ material.depthWrite = opaque || (state.opacity < 1 ? false : base.depthWrite);
331
+ }
332
+ });
333
+ }
334
+ export const sayMs = (text) => Math.min(9000, 3500 + 55 * Array.from(text).length);
335
+
336
+ function mesh(geometry, color, glow = false) {
337
+ const material = new THREE.MeshBasicMaterial({ color, ...(glow ? { transparent: true, opacity: 0.32, blending: THREE.AdditiveBlending, depthWrite: false } : {}) });
338
+ const node = new THREE.Mesh(geometry, material);
339
+ node.castShadow = false;
340
+ node.receiveShadow = false;
341
+ return node;
342
+ }
343
+ function triangle(vertices, color) {
344
+ const geometry = new THREE.BufferGeometry();
345
+ geometry.setAttribute('position', new THREE.Float32BufferAttribute(vertices, 3));
346
+ const node = mesh(geometry, color);
347
+ node.material.side = THREE.DoubleSide;
348
+ return node;
349
+ }
350
+ export function build(look, dress) {
351
+ const group = new THREE.Group();
352
+ group.rotation.order = 'YXZ';
353
+ group.name = `companion:${look}`;
354
+ if (look === 'lantern') {
355
+ // 30 triangles: core 8, cage 8, loop 6, additive glow 8.
356
+ group.add(mesh(new THREE.OctahedronGeometry(0.08), '#ffd27a'));
357
+ const cage = mesh(new THREE.OctahedronGeometry(0.105), '#5a4630');
358
+ cage.material.wireframe = true;
359
+ group.add(cage);
360
+ const loop = mesh(new THREE.RingGeometry(0.014, 0.023, 3), '#5a4630');
361
+ loop.material.side = THREE.DoubleSide;
362
+ loop.position.y = 0.12;
363
+ group.add(loop, mesh(new THREE.OctahedronGeometry(0.12), '#ffd27a', true));
364
+ } else if (dress?.species && dress.species !== 'songbird') {
365
+ paperSpecies(group, dress.species, mesh, triangle);
366
+ } else {
367
+ // Sixteen triangles: folded body, tail, beak, two wings with orange
368
+ // undersides, and a soft glow so white paper reads on pale paving.
369
+ group.scale.setScalar(2.2);
370
+ group.add(mesh(new THREE.OctahedronGeometry(0.06), '#ffd27a', true));
371
+ group.add(triangle([0, 0.02, 0.08, -0.025, -0.025, -0.05, 0, 0.025, -0.05, 0, 0.02, 0.08, 0, 0.025, -0.05, 0.025, -0.025, -0.05, 0, 0.025, -0.04, -0.035, 0, -0.1, 0.035, 0, -0.1], '#fff6e6'));
372
+ group.add(triangle([0, 0.02, 0.11, -0.014, 0, 0.06, 0.014, 0, 0.06], '#e8743b'));
373
+ for (const side of [-1, 1]) {
374
+ const vertices = [0, 0.02, 0.04, side * 0.11, 0.035, -0.05, 0, 0.02, -0.06];
375
+ // Match the winding across the two wings: white above, orange below.
376
+ const top = side > 0 ? vertices : [...vertices.slice(0, 3), ...vertices.slice(6), ...vertices.slice(3, 6)];
377
+ const bottom = [...top.slice(0, 3), ...top.slice(6), ...top.slice(3, 6)];
378
+ for (const [points, color] of [[top, '#fff6e6'], [bottom, '#f2a65a']]) {
379
+ const wing = triangle(points, color);
380
+ wing.material.side = THREE.FrontSide;
381
+ // One tagged top mesh per wing; its original underside follows it.
382
+ wing.userData[points === top ? 'wing' : 'wingUnder'] = side;
383
+ group.add(wing);
384
+ }
385
+ }
386
+ }
387
+ if (look === 'bird') { dressBird(group, dress, mesh, triangle); }
388
+ group.userData.normalScale = group.scale.x;
389
+ group.updateMatrixWorld(true);
390
+ const paperBounds = new THREE.Box3();
391
+ // Origin-centred sphere at normal scale covers every orientation, including
392
+ // the beak and worn item. Wing flutter rotates about that same origin.
393
+ let radius = 0;
394
+ const showVertices = [];
395
+ const vertex = new THREE.Vector3();
396
+ group.traverse((node) => {
397
+ const positions = node.geometry?.attributes.position;
398
+ if (!positions) { return; }
399
+ for (let i = 0; i < positions.count; i++) {
400
+ vertex.fromBufferAttribute(positions, i).applyMatrix4(node.matrixWorld);
401
+ radius = Math.max(radius, vertex.length());
402
+ if (node.material?.blending !== THREE.AdditiveBlending) {
403
+ paperBounds.expandByPoint(vertex);
404
+ const sample = vertex.clone();
405
+ sample.wing = node.userData.wing ?? node.userData.wingUnder;
406
+ sample.flutter = group.userData.flutter ?? 4;
407
+ showVertices.push(sample);
408
+ }
409
+ }
410
+ });
411
+ group.userData.size = paperBounds.getSize(new THREE.Vector3()).y;
412
+ group.userData.radius = radius;
413
+ group.userData.showVertices = showVertices;
414
+ return group;
415
+ }
416
+ function remove(root) {
417
+ root?.parent?.remove(root);
418
+ root?.traverse((node) => {
419
+ node.geometry?.dispose();
420
+ node.material?.dispose();
421
+ });
422
+ }
423
+
424
+ // Frames this far apart mean the page was hidden: the player was away.
425
+ export const AWAY_MS = 10000;
426
+
427
+ // Only an opted-in town sleeps a settled shoulder bird. Inputs are checked
428
+ // every frame; movement, speech, a pose, a connection or visibility change
429
+ // wakes it immediately. Elapsed idle time belongs to the next idle tick.
430
+ export function makeIdleTick() {
431
+ let previous = null, elapsed = 0;
432
+ return {
433
+ ready: false,
434
+ take(input, dt) {
435
+ const same = previous && input.length === previous.length && input.every((v, i) => Object.is(v, previous[i]));
436
+ previous = input;
437
+ if (!this.ready || !same) { elapsed = 0; return dt; }
438
+ elapsed += Math.max(0, dt);
439
+ if (elapsed < 0.2) {return null;}
440
+ const tick = elapsed; elapsed = 0; return tick;
441
+ },
442
+ };
443
+ }
444
+ const writeVector = (vector, x, y, z) => {
445
+ if (vector.x !== x || vector.y !== y || vector.z !== z) {vector.set(x, y, z);}
446
+ };
447
+
448
+ export function makeCompanion({ idle = false } = {}) {
449
+ let idleTick = makeIdleTick(), painted = null;
450
+ let dressJson = null;
451
+ let follower = null, look = null, pos = null, world = null, last = null, line = null, motion = null;
452
+ let seenAt = null, online = true;
453
+ let leading = null, route = null, flightFrom = null, quiet = null, abortedLead = null;
454
+ let showing = false, showHeld = false, showCamera = null, showElapsed = 0;
455
+ let hat = null, hatState = null, hatDropFrom = null, twirl = null, twirlYaw = 0;
456
+ const glows = new Map();
457
+ const clear = () => {
458
+ remove(hat);
459
+ remove(follower);
460
+ for (const { node } of glows.values()) {
461
+ remove(node);
462
+ }
463
+ glows.clear();
464
+ idleTick = makeIdleTick(); painted = null;
465
+ dressJson = null;
466
+ follower = look = pos = world = last = line = motion = null;
467
+ seenAt = null;
468
+ online = true;
469
+ leading = route = flightFrom = quiet = abortedLead = null;
470
+ showing = showHeld = false; showCamera = null; showElapsed = 0;
471
+ hat = hatState = hatDropFrom = twirl = null; twirlYaw = 0;
472
+ };
473
+ return {
474
+ clear,
475
+ dispose: clear,
476
+ frame(scene, local, hub, dt, now, visible, chat = null, busy = false, framing = null) {
477
+ if (world !== scene.three) {
478
+ clear();
479
+ world = scene.three;
480
+ }
481
+ const self = scene.multiplayer?.net?.selfId?.() ?? null;
482
+ const nodes = scene.three?.nodes;
483
+ const ownNode = local ? nodes?.get(local.id)?.node : null;
484
+ const c = sanitise(hub.companion?.c ?? null);
485
+ // Back from being away (frames stopped for AWAY_MS: a hidden page) or
486
+ // from a dropped connection: the current line is said again, once.
487
+ const state = scene.multiplayer?.net?.status?.()?.state;
488
+ const connected = state === undefined || state === 'connected';
489
+ if ((seenAt !== null && now - seenAt >= AWAY_MS) || (connected && !online)) {
490
+ idleTick = makeIdleTick();
491
+ last = null;
492
+ pos = route = flightFrom = null;
493
+ showing = showHeld = false; showCamera = null; showElapsed = 0;
494
+ remove(hat); hat = hatState = hatDropFrom = null;
495
+ twirl = { seen: hub.companion?.stamps ?? 0, since: twirl?.since ?? -Infinity };
496
+ }
497
+ seenAt = now;
498
+ online = connected;
499
+ if (last?.n !== hub.companion?.n) {
500
+ // Said when the words change or the follower is attached afresh (a
501
+ // reconnect); a new target alone does not say the old line again.
502
+ const again = !last?.c || last.c.say !== c?.say;
503
+ last = hub.companion;
504
+ line = !c?.say ? null : again ? { text: c.say, until: now + sayMs(c.say) } : line;
505
+ }
506
+ if (look !== c?.look || dressJson !== JSON.stringify(c?.dress ?? null)) {
507
+ remove(hat); hat = hatState = hatDropFrom = null; twirlYaw = 0;
508
+ remove(follower);
509
+ follower = c ? build(c.look, c.dress) : null;
510
+ painted = null; idleTick = makeIdleTick();
511
+ dressJson = JSON.stringify(c?.dress ?? null);
512
+ look = c?.look;
513
+ pos = motion = null;
514
+ leading = route = flightFrom = quiet = abortedLead = null;
515
+ showing = showHeld = false; showCamera = null; showElapsed = 0;
516
+ }
517
+ if (follower) {
518
+ const root = scene.three?.scene;
519
+ if (root && follower.parent !== root) {
520
+ root.add(follower);
521
+ }
522
+ follower.visible = Boolean(visible && ownNode && root && hub.place?.companion === true);
523
+ if (hat) { hat.visible = follower.visible; }
524
+ const at = local?.components.Transform;
525
+ const idleAt = idle && c?.at ? scene.getActor(c.at)?.components.Transform : null;
526
+ const tick = idle && at ? idleTick.take([
527
+ idleAt?.x, idleAt?.y, idleAt?.z, idleAt?.rotationY,
528
+ at.x, at.y, at.z, at.rotationY, c?.at, c?.look, c?.say, c?.pose, dressJson,
529
+ hub.companion?.n, hub.companion?.stamps, Boolean(chat), busy, Boolean(framing?.chatting),
530
+ follower.visible, ownNode, connected,
531
+ ], dt) : dt;
532
+ if (at && follower.visible && tick !== null) {
533
+ const dt = tick;
534
+ const actor = c.at ? scene.getActor(c.at) : null;
535
+ const pointAt = actor?.components.Transform ?? null;
536
+ const player = { x: at.x, y: at.y, z: at.z, yaw: (at.rotationY ?? 0) * Math.PI / 180 };
537
+ // A player teleport/reconnect returns home, never across a long route.
538
+ const teleported = motion && distance(motion, player) > 6;
539
+ if (abortedLead !== c.at) { abortedLead = null; }
540
+ if (teleported || (route && route.id === c.at && distance(route.player, player) > 6)) { abortedLead = c.at; }
541
+ if (teleported) { pos = flightFrom = null; showing = showHeld = false; showCamera = null; }
542
+ motion = restStep(motion, player, dt, Boolean(c.at));
543
+ const talking = hub.place?.companionChat && chat;
544
+ const showRequested = c.pose === 'show' && look === 'bird';
545
+ const cam = showRequested ? scene.three?.camera : null;
546
+ // The orbit renderer applies its scene lens after systems run. Frame
547
+ // against that lens even on the first frame, before cam.fov updates.
548
+ const fov = cam && scene.cameraControl === 'orbit' ? orbitFov(scene.data) : cam?.fov;
549
+ const camera = cam ? { position: cam.getWorldPosition(new THREE.Vector3()), up: new THREE.Vector3(0, 1, 0).applyQuaternion(cam.getWorldQuaternion(new THREE.Quaternion())), forward: cam.getWorldDirection(new THREE.Vector3()), fov: 2 * Math.atan(Math.tan(fov * Math.PI / 360) / cam.zoom) * 180 / Math.PI, near: cam.near } : null;
550
+ const show = showRequested && camera !== null;
551
+ if (show !== showing) {
552
+ if (show && !pos) { pos = followTarget(player, null, now / 1000); }
553
+ flightFrom = pos; showHeld = false; showCamera = null; showElapsed = 0; showing = show;
554
+ }
555
+ const resting = !show && !talking && look === 'bird' && motion.resting;
556
+ const before = pos;
557
+ route = leadStep(route, {
558
+ id: c.at, player, pointAt, pos, yaw: follower.rotation.y - twirlYaw, dt, now,
559
+ framing: framing ?? chat,
560
+ chatting: Boolean(show || talking || framing?.chatting || teleported || (c.at && abortedLead === c.at)),
561
+ });
562
+ const nextLeading = route?.id ?? null;
563
+ if (nextLeading !== leading) { flightFrom = pos; leading = nextLeading; }
564
+ const view = framing?.view ?? chat?.view ?? { w: cam?.aspect ?? 1, h: 1 };
565
+ const target = show ? showTarget(player, camera, view, follower.userData.size, follower.userData.radius, follower.userData.showVertices, now / 1000) : route?.pos ?? motionTarget(player, pointAt, now / 1000, resting, talking);
566
+ const flying = Boolean(route || flightFrom);
567
+ if (show && showHeld && showCamera && pos) { pos = carryShow(pos, showCamera, camera); }
568
+ if (show && !showHeld) {
569
+ // Reach the current camera target in 0.7 s at any starting distance.
570
+ showElapsed += Math.max(0, dt);
571
+ const progress = Math.min(1, showElapsed / 0.7);
572
+ pos = mix(flightFrom ?? pos ?? target, target, progress * progress * (3 - 2 * progress));
573
+ if (progress === 1) { showHeld = true; flightFrom = null; }
574
+ } else { pos = route ? route.pos : step(pos, target, show ? dt * 0.25 / 0.08 : dt, flightFrom, flying); }
575
+ if (show) {
576
+ pos = safeShow(pos, player, camera, follower.userData.radius);
577
+ // A spring can briefly lag the animated silhouette. Enforce the
578
+ // screen inset and player margin on the whole held box, as well as
579
+ // camera clearance.
580
+ if (showHeld && !showInside(pos, player, camera, view, follower.userData.showVertices, now / 1000)) { pos = { x: target.x, y: target.y, z: target.z }; }
581
+ showCamera = camera;
582
+ } else if (distance(pos, target) < 0.45) { flightFrom = null; }
583
+ const hatId = look === 'bird' && route?.phase === 'hover' && isHatStall(actor) ? route.id : null;
584
+ hatState = hatStep(hatState, hatId, now);
585
+ const wearing = !show && hatState && hatState.phase !== 'done';
586
+ twirl = twirlStep(twirl, hub.companion?.stamps ?? 0, now);
587
+ if (show) { twirl = { ...twirl, active: false, yaw: 0, hop: 0, pulse: 0 }; }
588
+ quiet = showRequested || twirl.active ? { scale: 1, opacity: 1 } : quietStep(quiet, isQuiet({ at: c.at, line: line && now < line.until, busy, talking, hat: wearing, twirl: twirl.active }), dt);
589
+ if (!idle || !painted || painted.scale !== quiet.scale || painted.opacity !== quiet.opacity || painted.show !== showRequested) {
590
+ appearance(follower, quiet, showRequested);
591
+ if (idle) {painted = { ...quiet, show: showRequested };}
592
+ }
593
+ // Snap only the final sub-millimetre of an opted-in rest. It cannot
594
+ // asymptotically rewrite the transform forever on a still shoulder.
595
+ if (idle && resting && !flying && !twirl.active && distance(pos, target) < 0.0001) {pos = { ...target };}
596
+ if (idle) {writeVector(follower.position, pos.x, pos.y + twirl.hop, pos.z);}
597
+ else {follower.position.set(pos.x, pos.y + twirl.hop, pos.z);}
598
+ if (show) {
599
+ const { forward, right, up } = showAxes(camera);
600
+ const offset = follower.position.clone().sub(camera.position);
601
+ const depth = offset.dot(forward);
602
+ follower.quaternion.copy(showRotation(camera, now / 1000, offset.dot(right) / depth, offset.dot(up) / depth));
603
+ }
604
+ else {
605
+ const pitch = route?.phase === 'hover' ? 35 * Math.PI / 180 : 0;
606
+ const ease = 1 - Math.exp(-Math.max(0, dt) / 0.15);
607
+ let rx = follower.rotation.x + (pitch - follower.rotation.x) * ease;
608
+ let rz = follower.rotation.z * (1 - ease);
609
+ let ry = follower.rotation.y - twirlYaw;
610
+ if (idle) {
611
+ if (Math.abs(rx - pitch) < 0.0001) {rx = pitch;}
612
+ if (Math.abs(rz) < 0.0001) {rz = 0;}
613
+ } else {
614
+ follower.rotation.x = rx; follower.rotation.z = rz; follower.rotation.y = ry;
615
+ }
616
+ const dx = !flying && pointAt ? pointAt.x - pos.x : before ? pos.x - before.x : 0;
617
+ const dz = !flying && pointAt ? pointAt.z - pos.z : before ? pos.z - before.z : 0;
618
+ if (talking) { ry = yawTo(pos, player); }
619
+ else if (route) { ry = route.yaw; }
620
+ else if (resting && !flying) { ry = player.yaw; }
621
+ else if (Math.hypot(dx, dz) > 0.0001) { ry = Math.atan2(dx, dz); }
622
+ ry += twirl.yaw;
623
+ if (idle) {writeVector(follower.rotation, rx, ry, rz);}
624
+ else {follower.rotation.y = ry;}
625
+ }
626
+ twirlYaw = twirl.yaw;
627
+ if (wearing && !hat) {
628
+ hat = new THREE.Group();
629
+ hat.name = 'companion:hat';
630
+ const brim = mesh(new THREE.CylinderGeometry(0.06, 0.06, 0.012, 8), '#53426d');
631
+ const crown = mesh(new THREE.CylinderGeometry(0.038, 0.045, 0.065, 8), '#765890');
632
+ crown.position.y = 0.035;
633
+ hat.add(brim, crown);
634
+ hat.position.copy(follower.userData.hatAnchor.position);
635
+ follower.add(hat);
636
+ }
637
+ if (follower.userData.worn) { follower.userData.worn.visible = !wearing; }
638
+ if (!show && hatState?.phase === 'drop' && hat) {
639
+ if (!hatDropFrom) {
640
+ follower.updateMatrixWorld(true);
641
+ root.attach(hat);
642
+ hatDropFrom = hat.position.clone();
643
+ }
644
+ hat.position.set(hatDropFrom.x + hatState.drop * 0.25, hatDropFrom.y - 1.5 * hatState.drop ** 2, hatDropFrom.z);
645
+ hat.rotation.z = hatState.drop * 2;
646
+ hat.traverse((node) => {
647
+ if (node.material) {
648
+ if (!node.material.transparent) {
649
+ node.material.transparent = true;
650
+ node.material.needsUpdate = true;
651
+ }
652
+ node.material.opacity = hatState.opacity;
653
+ node.material.depthWrite = false;
654
+ }
655
+ });
656
+ } else if (!wearing && hat) { remove(hat); hat = hatDropFrom = null; }
657
+ for (const child of follower.children) {
658
+ if (child.material?.blending === THREE.AdditiveBlending) {
659
+ const opacity = 0.32 * quiet.opacity * (showRequested ? 0.2 : 1 + twirl.pulse * 1.5);
660
+ if (!idle || child.material.opacity !== opacity) {child.material.opacity = opacity;}
661
+ if (idle) {writeVector(child.scale, 1 + twirl.pulse, 1 + twirl.pulse, 1 + twirl.pulse);}
662
+ else {child.scale.setScalar(1 + twirl.pulse);}
663
+ }
664
+ }
665
+ for (const child of follower.children) {
666
+ const wing = child.userData.wing ?? child.userData.wingUnder;
667
+ if (wing) {
668
+ const angle = wing * (show ? showWing(now / 1000, follower.userData.flutter ?? 4) : resting && !flying && !twirl.active ? -0.55 : Math.sin(now / 1000 * (follower.userData.flutter ?? 4) * Math.PI) * 0.45);
669
+ if (!idle || child.rotation.z !== angle) {child.rotation.z = angle;}
670
+ }
671
+ }
672
+ if (idle) {idleTick.ready = Boolean(!wearing && !twirl.active && !busy && !talking && !framing?.chatting && !showRequested && !(line && now < line.until) && (
673
+ // A waiting guide is idle too. Its small hover/flutter advances
674
+ // on the idle tick; a moving destination wakes it immediately.
675
+ route?.phase === 'hover' ||
676
+ (resting && !flying && !route && !c.at && distance(pos, target) === 0
677
+ && follower.rotation.x === 0 && follower.rotation.z === 0
678
+ && quiet.scale === 0.7 && quiet.opacity === 0.5)
679
+ ));}
680
+ }
681
+ }
682
+ for (const [id, entry] of glows) {
683
+ const actorId = scene.multiplayer?.avatars?.actors?.get(id);
684
+ if (!hub.glow?.has(id) || id === self || nodes?.get(actorId)?.node !== entry.parent) {
685
+ remove(entry.node);
686
+ glows.delete(id);
687
+ }
688
+ }
689
+ for (const id of hub.glow ?? []) {
690
+ const actorId = scene.multiplayer?.avatars?.actors?.get(id);
691
+ const parent = id !== self && actorId ? nodes?.get(actorId)?.node : null;
692
+ if (parent && !glows.has(id)) {
693
+ const node = mesh(new THREE.OctahedronGeometry(0.09), '#ffd27a', true);
694
+ node.position.set(0.4, HEIGHT, 0);
695
+ parent.add(node);
696
+ glows.set(id, { node, parent });
697
+ }
698
+ }
699
+ for (const { node } of glows.values()) {
700
+ node.visible = visible && hub.place?.companion === true;
701
+ }
702
+ // tiers.js only visits scene actors: these root/child nodes are neither
703
+ // counted nor culled on Low; glows still hide with their avatar parent.
704
+ },
705
+ screen(cam, view, project) {
706
+ return follower?.visible && pos ? project(cam, pos.x, pos.y, pos.z, view) : null;
707
+ },
708
+ labels(cam, view, project, now) {
709
+ if (!follower?.visible || !line || now >= line.until || !pos) {
710
+ return [];
711
+ }
712
+ const screen = project(cam, pos.x, pos.y + 0.22, pos.z, view);
713
+ return screen ? [{ id: 'companion:line', ...screen, text: line.text, speech: true, npc: true }] : [];
714
+ },
715
+ };
716
+ }