castle-web-cli 0.4.229 → 0.4.231

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 (259) hide show
  1. package/dist/agent-prompts.d.ts +2 -0
  2. package/dist/agent-prompts.js +16 -8
  3. package/dist/agent.d.ts +2 -0
  4. package/dist/agent.js +21 -21
  5. package/dist/api.d.ts +28 -2
  6. package/dist/api.js +74 -16
  7. package/dist/castle-host/host.d.ts +91 -0
  8. package/dist/castle-host/host.js +860 -3
  9. package/dist/castleJson.d.ts +44 -0
  10. package/dist/castleJson.js +131 -0
  11. package/dist/check.js +27 -1
  12. package/dist/contentPack.d.ts +49 -0
  13. package/dist/contentPack.js +273 -0
  14. package/dist/devExperiments.d.ts +21 -0
  15. package/dist/devExperiments.js +139 -0
  16. package/dist/devHub.d.ts +55 -0
  17. package/dist/devHub.js +187 -0
  18. package/dist/devSaveStorage.d.ts +36 -0
  19. package/dist/devSaveStorage.js +469 -0
  20. package/dist/devSessionChild.js +25 -13
  21. package/dist/devSessionServer.d.ts +14 -1
  22. package/dist/devSessionServer.js +237 -46
  23. package/dist/devSessionStorage.d.ts +9 -0
  24. package/dist/devSessionStorage.js +66 -1
  25. package/dist/experimentAssignment.d.ts +15 -0
  26. package/dist/experimentAssignment.js +41 -0
  27. package/dist/importCheckHook.d.ts +40 -0
  28. package/dist/importCheckHook.js +171 -0
  29. package/dist/importRegression.d.ts +15 -0
  30. package/dist/importRegression.js +100 -0
  31. package/dist/importTrust.d.ts +2 -0
  32. package/dist/importTrust.js +27 -0
  33. package/dist/importUpdateHook.d.ts +18 -0
  34. package/dist/importUpdateHook.js +31 -8
  35. package/dist/importUpdateHookRunner.js +19 -7
  36. package/dist/imports.d.ts +16 -0
  37. package/dist/imports.js +141 -31
  38. package/dist/index.js +3 -1
  39. package/dist/init.d.ts +3 -0
  40. package/dist/init.js +126 -9
  41. package/dist/install.js +4 -1
  42. package/dist/localPaths.js +4 -0
  43. package/dist/login.js +2 -2
  44. package/dist/platformDoc.js +3 -8
  45. package/dist/playPagePolicy.js +3 -1
  46. package/dist/remix.js +5 -0
  47. package/dist/routerTaskReport.d.ts +28 -0
  48. package/dist/routerTaskReport.js +56 -0
  49. package/dist/save-deck.d.ts +18 -0
  50. package/dist/save-deck.js +142 -6
  51. package/dist/serve.d.ts +8 -0
  52. package/dist/serve.js +99 -14
  53. package/dist/serverBundle.d.ts +1 -1
  54. package/dist/serverBundle.js +5 -1
  55. package/dist/webSourceSync.d.ts +2 -0
  56. package/dist/webSourceSync.js +2 -0
  57. package/kits/base/CLAUDE.md +2 -3
  58. package/kits/base/castle.json +1 -1
  59. package/kits/base/sdk/README.md +406 -53
  60. package/kits/base/sdk/agent.js +4 -4
  61. package/kits/base/sdk/avatar.d.ts +12 -0
  62. package/kits/base/sdk/avatar.js +23 -0
  63. package/kits/base/sdk/castle.d.ts +9 -0
  64. package/kits/base/sdk/castle.js +5 -0
  65. package/kits/base/sdk/commands.d.ts +223 -0
  66. package/kits/base/sdk/commands.js +16 -0
  67. package/kits/base/sdk/context.d.ts +6 -0
  68. package/kits/base/sdk/experiments.d.ts +15 -0
  69. package/kits/base/sdk/experiments.js +83 -0
  70. package/kits/base/sdk/hub.d.ts +85 -0
  71. package/kits/base/sdk/hub.js +107 -0
  72. package/kits/base/sdk/multiplayer.d.ts +45 -1
  73. package/kits/base/sdk/multiplayer.js +158 -8
  74. package/kits/base/sdk/save.d.ts +197 -0
  75. package/kits/base/sdk/save.js +525 -0
  76. package/kits/base/sdk/saveCoordinator.d.ts +39 -0
  77. package/kits/base/sdk/saveCoordinator.js +252 -0
  78. package/kits/base/sdk/server/hub.d.ts +169 -0
  79. package/kits/base/sdk/server/hub.js +125 -0
  80. package/kits/base/sdk/server/platformHandle.d.ts +42 -1
  81. package/kits/base/sdk/server/storage.d.ts +58 -4
  82. package/kits/base/sdk/server/storage.js +25 -5
  83. package/kits/base/sdk/server/wrapper.d.ts +36 -2
  84. package/kits/base/sdk/server/wrapper.js +92 -11
  85. package/kits/base/sdk/store.d.ts +3 -2
  86. package/kits/base/sdk/store.js +5 -0
  87. package/kits/base/sdk/transport.d.ts +2 -1
  88. package/kits/base/sdk/transport.js +13 -1
  89. package/kits/hub-game/.prettierrc +5 -0
  90. package/kits/hub-game/CLAUDE.md +149 -0
  91. package/kits/hub-game/blueprints/avatar-0.scene +28 -0
  92. package/kits/hub-game/blueprints/avatar-1.scene +28 -0
  93. package/kits/hub-game/blueprints/avatar-2.scene +28 -0
  94. package/kits/hub-game/blueprints/avatar-3.scene +28 -0
  95. package/kits/hub-game/blueprints/bean/avatar-0.scene +28 -0
  96. package/kits/hub-game/blueprints/bean/avatar-1.scene +28 -0
  97. package/kits/hub-game/blueprints/bean/avatar-2.scene +28 -0
  98. package/kits/hub-game/blueprints/bean/avatar-3.scene +28 -0
  99. package/kits/hub-game/blueprints/blocky/avatar-0.scene +28 -0
  100. package/kits/hub-game/blueprints/blocky/avatar-1.scene +28 -0
  101. package/kits/hub-game/blueprints/blocky/avatar-2.scene +28 -0
  102. package/kits/hub-game/blueprints/blocky/avatar-3.scene +28 -0
  103. package/kits/hub-game/blueprints/pixel/avatar-0.scene +28 -0
  104. package/kits/hub-game/blueprints/pixel/avatar-1.scene +28 -0
  105. package/kits/hub-game/blueprints/pixel/avatar-2.scene +28 -0
  106. package/kits/hub-game/blueprints/pixel/avatar-3.scene +28 -0
  107. package/kits/hub-game/castle.json +96 -0
  108. package/kits/hub-game/code/client/attention.js +133 -0
  109. package/kits/hub-game/code/client/avatar.js +288 -0
  110. package/kits/hub-game/code/client/cabinets.js +90 -0
  111. package/kits/hub-game/code/client/chat.js +135 -0
  112. package/kits/hub-game/code/client/chrome.js +1035 -0
  113. package/kits/hub-game/code/client/doorFrame.js +15 -0
  114. package/kits/hub-game/code/client/firstJoin.js +14 -0
  115. package/kits/hub-game/code/client/grab.js +376 -0
  116. package/kits/hub-game/code/client/hookLayer.js +236 -0
  117. package/kits/hub-game/code/client/idle.js +326 -0
  118. package/kits/hub-game/code/client/keys.js +48 -0
  119. package/kits/hub-game/code/client/pack.js +232 -0
  120. package/kits/hub-game/code/client/packFormat.js +397 -0
  121. package/kits/hub-game/code/client/say.js +127 -0
  122. package/kits/hub-game/code/client/sha256.js +80 -0
  123. package/kits/hub-game/code/client/sound.js +147 -0
  124. package/kits/hub-game/code/client/state.js +143 -0
  125. package/kits/hub-game/code/client/talk.js +233 -0
  126. package/kits/hub-game/code/client/tiers.js +480 -0
  127. package/kits/hub-game/code/client/together.js +440 -0
  128. package/kits/hub-game/code/client/wear.js +149 -0
  129. package/kits/hub-game/code/server/actors.js +627 -0
  130. package/kits/hub-game/code/server/blocks.js +103 -0
  131. package/kits/hub-game/code/server/cabinets.js +309 -0
  132. package/kits/hub-game/code/server/game.js +137 -0
  133. package/kits/hub-game/code/server/grab.js +248 -0
  134. package/kits/hub-game/code/server/history.js +96 -0
  135. package/kits/hub-game/code/server/hub.js +1998 -0
  136. package/kits/hub-game/code/server/idle.js +412 -0
  137. package/kits/hub-game/code/server/index.js +64 -0
  138. package/kits/hub-game/code/server/labels.js +59 -0
  139. package/kits/hub-game/code/server/manifest.js +554 -0
  140. package/kits/hub-game/code/server/npcs.js +733 -0
  141. package/kits/hub-game/code/server/party.js +439 -0
  142. package/kits/hub-game/code/server/place.js +43 -0
  143. package/kits/hub-game/code/server/say.js +83 -0
  144. package/kits/hub-game/code/server/wear.js +142 -0
  145. package/kits/hub-game/code/systems/hub.js +2347 -0
  146. package/kits/hub-game/docs/content-pack.md +151 -0
  147. package/kits/hub-game/docs/contract.md +1209 -0
  148. package/kits/hub-game/docs/style.md +137 -0
  149. package/kits/hub-game/drawings/blocky/castle-eye.sprite +58 -0
  150. package/kits/hub-game/drawings/blocky/dash.sprite +59 -0
  151. package/kits/hub-game/drawings/blocky/pom.sprite +59 -0
  152. package/kits/hub-game/drawings/blocky/tabby.sprite +59 -0
  153. package/kits/hub-game/drawings/pixel/castle-arm.sprite +13 -0
  154. package/kits/hub-game/drawings/pixel/castle-body.sprite +23 -0
  155. package/kits/hub-game/drawings/pixel/castle-leg.sprite +12 -0
  156. package/kits/hub-game/drawings/pixel/kai-arm.sprite +14 -0
  157. package/kits/hub-game/drawings/pixel/kai-head.sprite +24 -0
  158. package/kits/hub-game/drawings/pixel/kai-leg.sprite +15 -0
  159. package/kits/hub-game/drawings/pixel/kai-torso.sprite +18 -0
  160. package/kits/hub-game/drawings/pixel/mimi-arm.sprite +13 -0
  161. package/kits/hub-game/drawings/pixel/mimi-head.sprite +23 -0
  162. package/kits/hub-game/drawings/pixel/mimi-leg.sprite +15 -0
  163. package/kits/hub-game/drawings/pixel/mimi-torso.sprite +18 -0
  164. package/kits/hub-game/drawings/pixel/nox-arm.sprite +13 -0
  165. package/kits/hub-game/drawings/pixel/nox-head.sprite +21 -0
  166. package/kits/hub-game/drawings/pixel/nox-leg.sprite +14 -0
  167. package/kits/hub-game/drawings/pixel/nox-torso.sprite +18 -0
  168. package/kits/hub-game/eslint.config.js +20 -0
  169. package/kits/hub-game/fonts.generated.js +9 -0
  170. package/kits/hub-game/index.html +22 -0
  171. package/kits/hub-game/main.jsx +6 -0
  172. package/kits/hub-game/models/avatar-0.pxmodel +21 -0
  173. package/kits/hub-game/models/avatar-1.pxmodel +24 -0
  174. package/kits/hub-game/models/avatar-2.pxmodel +27 -0
  175. package/kits/hub-game/models/avatar-3.pxmodel +22 -0
  176. package/kits/hub-game/models/bean/avatar-0.pxmodel +19 -0
  177. package/kits/hub-game/models/bean/avatar-1.pxmodel +24 -0
  178. package/kits/hub-game/models/bean/avatar-2.pxmodel +22 -0
  179. package/kits/hub-game/models/bean/avatar-3.pxmodel +24 -0
  180. package/kits/hub-game/models/blocky/avatar-0.pxmodel +21 -0
  181. package/kits/hub-game/models/blocky/avatar-1.pxmodel +30 -0
  182. package/kits/hub-game/models/blocky/avatar-2.pxmodel +28 -0
  183. package/kits/hub-game/models/blocky/avatar-3.pxmodel +27 -0
  184. package/kits/hub-game/models/pixel/avatar-0.pxmodel +24 -0
  185. package/kits/hub-game/models/pixel/avatar-1.pxmodel +16 -0
  186. package/kits/hub-game/models/pixel/avatar-2.pxmodel +19 -0
  187. package/kits/hub-game/models/pixel/avatar-3.pxmodel +23 -0
  188. package/kits/hub-game/package-lock.json +365 -0
  189. package/kits/hub-game/package.json +32 -0
  190. package/kits/hub-game/scenes/main.scene +318 -0
  191. package/kits/hub-game/scripts/check.mjs +339 -0
  192. package/kits/hub-game/scripts/fixtures/sdk-stub.mjs +3 -0
  193. package/kits/hub-game/scripts/gen-avatars-bean.mjs +748 -0
  194. package/kits/hub-game/scripts/gen-avatars-blocky.mjs +607 -0
  195. package/kits/hub-game/scripts/gen-avatars-pixel.mjs +771 -0
  196. package/kits/hub-game/scripts/gen-avatars.mjs +621 -0
  197. package/kits/hub-game/scripts/pack.mjs +192 -0
  198. package/kits/hub-game/scripts/test-actors.mjs +666 -0
  199. package/kits/hub-game/scripts/test-attention.mjs +103 -0
  200. package/kits/hub-game/scripts/test-avatar.mjs +472 -0
  201. package/kits/hub-game/scripts/test-ban-join.mjs +194 -0
  202. package/kits/hub-game/scripts/test-blocks.mjs +351 -0
  203. package/kits/hub-game/scripts/test-chat.mjs +98 -0
  204. package/kits/hub-game/scripts/test-classic.mjs +590 -0
  205. package/kits/hub-game/scripts/test-door-jump.mjs +131 -0
  206. package/kits/hub-game/scripts/test-door.mjs +56 -0
  207. package/kits/hub-game/scripts/test-grab-client.mjs +328 -0
  208. package/kits/hub-game/scripts/test-grab.mjs +331 -0
  209. package/kits/hub-game/scripts/test-hub-ops.mjs +835 -0
  210. package/kits/hub-game/scripts/test-hub-trip.mjs +1518 -0
  211. package/kits/hub-game/scripts/test-idle.mjs +518 -0
  212. package/kits/hub-game/scripts/test-interest.mjs +413 -0
  213. package/kits/hub-game/scripts/test-keys.mjs +50 -0
  214. package/kits/hub-game/scripts/test-manifest.mjs +270 -0
  215. package/kits/hub-game/scripts/test-no-forms.mjs +16 -0
  216. package/kits/hub-game/scripts/test-npcs.mjs +724 -0
  217. package/kits/hub-game/scripts/test-pack.mjs +424 -0
  218. package/kits/hub-game/scripts/test-party.mjs +369 -0
  219. package/kits/hub-game/scripts/test-say.mjs +149 -0
  220. package/kits/hub-game/scripts/test-tiers.mjs +666 -0
  221. package/kits/hub-game/scripts/test-together.mjs +215 -0
  222. package/kits/hub-game/theme.style +3 -0
  223. package/kits/multiplayer-3d/castle.json +5 -5
  224. package/kits/multiplayer-3d/code/client/avatars.js +101 -1
  225. package/kits/multiplayer-3d/code/server/players.js +4 -1
  226. package/kits/multiplayer-3d/code/server/sceneBodies.js +27 -6
  227. package/kits/multiplayer-3d/code/server/world.js +20 -7
  228. package/kits/multiplayer-3d/code/systems/multiplayer.js +222 -11
  229. package/kits/physics-2d/CLAUDE.md +2 -0
  230. package/kits/physics-2d/castle.json +2 -2
  231. package/kits/physics-2d/engine/art.js +13 -0
  232. package/kits/physics-2d/engine/assets.js +4 -2
  233. package/kits/physics-2d/engine/scene.js +117 -5
  234. package/kits/physics-2d/package.json +1 -1
  235. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +254 -0
  236. package/kits/physics-3d/CLAUDE.md +285 -1
  237. package/kits/physics-3d/behaviors/Player.jsx +74 -1
  238. package/kits/physics-3d/castle.json +3 -3
  239. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +33 -5
  240. package/kits/physics-3d/engine3d/actornode.js +253 -0
  241. package/kits/physics-3d/engine3d/artobjects.js +2 -2
  242. package/kits/physics-3d/engine3d/materials.js +29 -1
  243. package/kits/physics-3d/engine3d/nearshadows.js +600 -0
  244. package/kits/physics-3d/engine3d/unchanged.js +153 -0
  245. package/kits/physics-3d/engine3d/world3d.js +527 -5
  246. package/kits/physics-3d/package.json +1 -1
  247. package/kits/physics-3d/scripts/test-camera-follow.mjs +533 -0
  248. package/kits/physics-3d/scripts/test-near-shadows.mjs +1073 -0
  249. package/kits/physics-3d/scripts/test-static-actors.mjs +662 -0
  250. package/kits/physics-3d/scripts/test-static-passes.mjs +459 -0
  251. package/kits/physics-3d/scripts/test-static-physics.mjs +128 -0
  252. package/kits/physics-3d/systems/physics3d.js +187 -5
  253. package/kits/real-time/castle.json +2 -2
  254. package/kits/real-time/code/client/connection.js +77 -7
  255. package/kits/real-time/code/client/gameHooks.js +63 -3
  256. package/kits/real-time/code/client/messages.js +7 -0
  257. package/kits/real-time/code/server/gameHooks.js +24 -0
  258. package/kits/real-time/code/server/session.js +390 -22
  259. package/package.json +2 -2
@@ -17,6 +17,11 @@ import {
17
17
  import { parseModelCached, buildModelNode, modelArtSignature, animateModelParts } from './pxmodel';
18
18
  import { animateMotion } from './motion';
19
19
  import { modelRefSignature } from './modelrefs';
20
+ import { lookIsEnabled } from './look';
21
+ import { artReady } from '@imports/castle.physics-2d/engine/art';
22
+ import { ActorNode } from './actornode.js';
23
+ import { remember, sameAs, recordReads } from './unchanged.js';
24
+ import { renderWithNearShadows, dropNearShadows } from './nearshadows.js';
20
25
  import {
21
26
  takeModel,
22
27
  releaseModel,
@@ -78,7 +83,26 @@ export function makeWorld3D(canvas) {
78
83
  renderer,
79
84
  composer,
80
85
  nodes: new Map(),
86
+ // The scene path `nodes` were built for, and the nodes of scenes the
87
+ // runtime keeps resident while another one plays (`residentScenes`).
88
+ scenePath: undefined,
89
+ parked: new Map(),
81
90
  models: new Map(),
91
+ // For scenes that set `"engine": { "skipUnchangedActors": true }`
92
+ // (`syncActorsSkipping`): whether the scene now playing is one, each model
93
+ // file's signature with what it was read from, and the counts that say
94
+ // when those are due a check.
95
+ skipping: { on: false },
96
+ modelSigs: new Map(),
97
+ sigEpoch: 0,
98
+ syncCount: 0,
99
+ syncDepth: 0,
100
+ generation: 0,
101
+ snapshots: new WeakMap(),
102
+ // For scenes that set `"engine": { "shadows": { "distance": n } }`
103
+ // (nearshadows.js): the shadow the engine draws for them, which is its
104
+ // own; the sun's is never written.
105
+ nearShadows: null,
82
106
  instances: new Map(),
83
107
  instanceModels: false,
84
108
  debugLines,
@@ -152,7 +176,11 @@ export function syncGround(world, setting, sprites) {
152
176
  });
153
177
  world.ground.material.dispose();
154
178
  world.ground.material = material;
155
- world.grid.visible = !texture;
179
+ // `"none": true`: no ground at all, drawn or stood on (the physics system
180
+ // leaves its collider out too).
181
+ const none = setting?.none === true;
182
+ world.ground.visible = !none;
183
+ world.grid.visible = !texture && !none;
156
184
  }
157
185
 
158
186
  // The signature suffix for an actor's Model component: the model file's text
@@ -250,6 +278,18 @@ const DEG = Math.PI / 180;
250
278
  // `actor.runtime.quat`; everything else rotates by the Transform's euler
251
279
  // degrees.
252
280
  export function syncActors(world, runtime, sprites, dt = 0) {
281
+ if (runtime.skipsUnchangedActors === true && world.disposed !== true) {
282
+ syncActorsSkipping(world, runtime, sprites, dt);
283
+ return;
284
+ }
285
+ if (world.skipping.on) stopSkipping(world);
286
+ // A scene is keyed by its content as well as its path (`sceneKey`), so a
287
+ // town and a mounted game that both call theirs `scenes/main.scene` are
288
+ // different scenes here.
289
+ const key = runtime.sceneKey ?? runtime.scenePath;
290
+ if (key !== world.scenePath) {
291
+ swapSceneNodes(world, key, runtime.residentScenes);
292
+ }
253
293
  syncGround(world, runtime.data?.ground, sprites);
254
294
  const seen = new Set();
255
295
  for (const actor of runtime.getActors()) {
@@ -278,6 +318,51 @@ export function syncActors(world, runtime, sprites, dt = 0) {
278
318
  }
279
319
  }
280
320
 
321
+ // A scene load. The nodes built for the scene being left are parked when the
322
+ // runtime names that scene resident (`runtime.residentScenes`, a Set of scene
323
+ // keys -- `runtime.sceneKey`; the hub keeps the town it will walk back into), and released
324
+ // otherwise; the nodes parked for the scene arriving are put back, so a return
325
+ // redraws it without rebuilding a mesh. The sync that follows reuses a parked
326
+ // node only where its actor's signature still matches. A parked scene the
327
+ // runtime no longer names is released.
328
+ function swapSceneNodes(world, path, resident) {
329
+ const keep = resident instanceof Set ? resident : new Set();
330
+ if (world.scenePath !== undefined && keep.has(world.scenePath) && world.scenePath !== path) {
331
+ const parked = new Map();
332
+ for (const [id, entry] of world.nodes) {
333
+ if (entry.instancedRig) {
334
+ // An instanced rig is drawn by its model's shared instances wherever
335
+ // its node is; parking it would leave it drawn in the next scene.
336
+ releaseActorNode(world, entry);
337
+ continue;
338
+ }
339
+ world.scene.remove(entry.node);
340
+ parked.set(id, entry);
341
+ }
342
+ world.parked.set(world.scenePath, parked);
343
+ world.nodes = new Map();
344
+ }
345
+ // Nodes not parked stay where they are: the sync releases those whose actor
346
+ // is gone and reuses those an actor of the same id and look still has.
347
+ const back = world.parked.get(path);
348
+ if (back) {
349
+ world.parked.delete(path);
350
+ for (const [id, entry] of back) {
351
+ const current = world.nodes.get(id);
352
+ if (current) releaseActorNode(world, current);
353
+ world.scene.add(entry.node);
354
+ world.nodes.set(id, entry);
355
+ }
356
+ }
357
+ for (const [parkedPath, parked] of world.parked) {
358
+ if (!keep.has(parkedPath)) {
359
+ for (const entry of parked.values()) releaseActorNode(world, entry);
360
+ world.parked.delete(parkedPath);
361
+ }
362
+ }
363
+ world.scenePath = path;
364
+ }
365
+
281
366
  export function resizeWorld(world, width, height) {
282
367
  world.renderer.setSize(width, height, false);
283
368
  world.composer.setSize(width, height);
@@ -285,7 +370,26 @@ export function resizeWorld(world, width, height) {
285
370
  world.camera.updateProjectionMatrix();
286
371
  }
287
372
 
288
- export function renderWorld(world) {
373
+ // `runtime` is given by the player, whose scene may have asked for shadows
374
+ // near the view only (`"engine": { "shadows": { "distance": n } }`,
375
+ // nearshadows.js). The editors give none and draw every scene the one way.
376
+ export function renderWorld(world, runtime) {
377
+ // A world with nothing of the mode's, whose scene did not ask (or which is
378
+ // being disposed): the two statements this function always was.
379
+ const distance = runtime?.nearShadowDistance ?? 0;
380
+ if (!world.nearShadows && !(distance > 0 && world.disposed !== true)) {
381
+ drawWorld(world);
382
+ return;
383
+ }
384
+ renderWithNearShadows(
385
+ world,
386
+ distance,
387
+ () => fitShadowBias(world),
388
+ () => world.composer.render()
389
+ );
390
+ }
391
+
392
+ function drawWorld(world) {
289
393
  fitShadowBias(world);
290
394
  world.composer.render();
291
395
  }
@@ -314,7 +418,425 @@ function fitShadowBias(world) {
314
418
  }
315
419
 
316
420
  export function disposeWorld(world) {
317
- for (const entry of world.nodes.values()) releaseActorNode(world, entry);
318
- world.nodes.clear();
319
- world.renderer.dispose();
421
+ // Releasing a node runs `dispose` listeners, which may sync this world
422
+ // again. From here on it never skips (`syncActors` reads `disposed`), so
423
+ // such a sync writes nothing down; what was written down before goes now,
424
+ // and again after the listeners have run, whether or not one throws.
425
+ world.disposed = true;
426
+ // A `dispose` listener on the near-shadow mode's map that throws does not
427
+ // keep the rest from being released.
428
+ try {
429
+ dropNearShadows(world);
430
+ } finally {
431
+ disposeNodes(world);
432
+ }
433
+ }
434
+
435
+ function disposeNodes(world) {
436
+ world.skipping.on = false;
437
+ leavingTheEngine(world);
438
+ forgetEverything(world);
439
+ try {
440
+ for (const entry of world.nodes.values()) releaseActorNode(world, entry);
441
+ world.nodes.clear();
442
+ for (const parked of world.parked.values()) {
443
+ for (const entry of parked.values()) releaseActorNode(world, entry);
444
+ }
445
+ world.parked.clear();
446
+ world.renderer.dispose();
447
+ } finally {
448
+ forgetEverything(world);
449
+ }
450
+ }
451
+
452
+ //
453
+ // Scenes that set `"engine": { "skipUnchangedActors": true }`
454
+ //
455
+ // `syncActors` for such a scene. It draws what `syncActors` draws; what it
456
+ // leaves out is building, for every actor on every frame, a signature whose
457
+ // inputs read as they did when the node was built, and (in ActorNode)
458
+ // recomputing matrices nothing has moved.
459
+ //
460
+ // The rule it is built to:
461
+ //
462
+ // Fast-path state (snapshots, pass marks, cached signatures) is trusted only
463
+ // across a span in which no code outside the engine has run. A pass in which
464
+ // the engine calls out (any callback), is re-entered, or sees the scene
465
+ // change, finishes exactly as main would and leaves no fast-path state
466
+ // behind.
467
+ //
468
+ // How: `world.generation` moves whenever code outside the engine may run inside
469
+ // a pass, and `world.syncDepth` says whether a pass is already running. A pass
470
+ // notes the generation it started at and looks again before each actor; once
471
+ // it has moved, the rest of the pass does for each actor what `syncActors`
472
+ // does (the signature built and compared, the rotation set) and writes nothing
473
+ // down, and when the outermost pass ends everything written down before is
474
+ // dropped. It is dropped as well when the outermost pass ends by throwing,
475
+ // whatever the generation says. A pass entered while another is running starts
476
+ // that way. There are no marks on entries: each pass has its own `seen`, as
477
+ // `syncActors` has.
478
+ //
479
+ // The generation is moved in one place, `leavingTheEngine`, called BEFORE the
480
+ // engine does anything in a pass that can run someone else's code. Nothing is
481
+ // inferred afterwards from what changed. three.js runs listeners
482
+ // (EventDispatcher) from `add`, `remove`, `removeFromParent`, `clear` and
483
+ // `attach` on an object (`added`, `removed`, `childadded`, `childremoved`) and
484
+ // from `dispose` on a geometry, material, texture or render target. A pass
485
+ // reaches those through, and only through:
486
+ // - `swapSceneNodes` (a scene change: nodes added, removed, released);
487
+ // - `syncGround` when the ground's signature differs (the old material
488
+ // disposed), asked beforehand by `groundIsDressed`;
489
+ // - `buildNode` (a node built: its old one released, the new one added, and
490
+ // for an instanced model `makeInstances`);
491
+ // - `releaseNode` (a node removed, its meshes disposed, `removeInstances`);
492
+ // - `drawInstances` (an instanced mesh replaced: removed, disposed, added).
493
+ // Whether it will replace one is its own business, so a world that has
494
+ // instances runs every pass main's way from the start;
495
+ // and it calls a deck's function in one place:
496
+ // - `scene.userData.groundHeight` (motion.js `airSpeed`), while a walking
497
+ // model's parts are animated. A scene that has one runs every pass main's
498
+ // way from the start; a node moved under something else that has one moves
499
+ // the generation before that node is animated.
500
+ // `syncActors` called from any of those, keyed or not, is the re-entry.
501
+ // Building a model (`takeModel`, `buildModelNode`, `copyModel`, `fillNode`)
502
+ // adds to objects that were made a moment ago and that nothing can be
503
+ // listening to; it happens inside `buildNode` regardless. Nothing else in a
504
+ // pass leaves the engine: reading plain components and the deck's `sprites`
505
+ // and `files` tables, `runtime.getActors`, three.js math, and building
506
+ // signatures from plain data (`JSON.stringify` calls no one for those). A
507
+ // scene whose components are not plain stored data is outside the key's terms
508
+ // (CLAUDE.md).
509
+ //
510
+ // What is written down, and where:
511
+ // - `world.snapshots`, a WeakMap from a node entry to what the node was built
512
+ // from (the Shape and Model as remembered, the art read, the model
513
+ // signature) and how it was last turned. Dropped by putting a new WeakMap
514
+ // in its place. An entry that is released, or held by someone else, holds
515
+ // none of it.
516
+ // - `world.modelSigs`, a Map from a model file to its signature and the reads
517
+ // it was built from. Cleared.
518
+ // - `world.sigEpoch`, `world.syncCount`, `world.generation`, `world.syncDepth`,
519
+ // `world.skipping.on`: numbers and a flag.
520
+ // - on an ActorNode, `computedFrom`: numbers only (actornode.js), so it can
521
+ // hold nothing; cleared when its node is released, when the world leaves
522
+ // the skipping path or is disposed, and by the node itself when it finds
523
+ // the switch off.
524
+ // Snapshots are kept from one pass to the next, across which deck code does
525
+ // run; they are not trusted there but read against the live components and
526
+ // node on every use.
527
+
528
+ // How many model files' signatures are kept before the lot is dropped and
529
+ // built again as needed.
530
+ const MODEL_SIGS_LIMIT = 512;
531
+
532
+ // Called before the engine, inside a pass, does anything that can run code
533
+ // that is not the engine's. See the list above.
534
+ function leavingTheEngine(world) {
535
+ world.generation += 1;
536
+ }
537
+
538
+ // The scene now playing did not ask: every node is a plain Group again and
539
+ // nothing read from the scene that did is kept. If a pass of a scene that did
540
+ // ask is running underneath (this sync was called from inside it), it is told.
541
+ function stopSkipping(world) {
542
+ world.skipping.on = false;
543
+ leavingTheEngine(world);
544
+ forgetEverything(world);
545
+ }
546
+
547
+ // Drops everything a skipping pass wrote down about the scene.
548
+ function forgetSnapshots(world) {
549
+ world.snapshots = new WeakMap();
550
+ world.modelSigs.clear();
551
+ }
552
+
553
+ // And what each node, playing or parked, remembers of its own matrices.
554
+ function forgetEverything(world) {
555
+ forgetSnapshots(world);
556
+ const forget = (entry) => {
557
+ if (entry.node.computedFrom) entry.node.computedFrom = null;
558
+ };
559
+ world.nodes.forEach(forget);
560
+ for (const parked of world.parked.values()) parked.forEach(forget);
561
+ }
562
+
563
+ function syncActorsSkipping(world, runtime, sprites, dt) {
564
+ // Entered while a pass is running: that pass is no longer alone.
565
+ if (world.syncDepth > 0) leavingTheEngine(world);
566
+ const outermost = world.syncDepth === 0;
567
+ const started = world.generation;
568
+ world.skipping.on = true;
569
+ world.syncDepth += 1;
570
+ let finished = false;
571
+ try {
572
+ skippingPass(world, runtime, sprites, dt, outermost ? started : -1);
573
+ finished = true;
574
+ } finally {
575
+ world.syncDepth -= 1;
576
+ if (outermost && (!finished || world.generation !== started)) forgetSnapshots(world);
577
+ }
578
+ }
579
+
580
+ // One pass. `started` is the generation it may trust its state at; a pass
581
+ // entered inside another is given one that never matches.
582
+ function skippingPass(world, runtime, sprites, dt, started) {
583
+ beginPass(world, runtime, sprites);
584
+ if (world.generation === started) {
585
+ world.syncCount += 1;
586
+ world.sigEpoch += 1;
587
+ }
588
+ const seen = new Set();
589
+ for (const actor of runtime.getActors()) {
590
+ const t = actor.components.Transform;
591
+ if (!t) continue;
592
+ seen.add(actor.id);
593
+ const entry = placeActor(world, actor, t, sprites, runtime.files, started);
594
+ animateModelParts(entry, dt);
595
+ animateMotion(entry, dt, actor);
596
+ }
597
+ // While the pass was alone every actor seen has its node and no node was
598
+ // released, so as many nodes as actors seen means no node has lost its actor.
599
+ if (world.generation !== started || seen.size !== world.nodes.size) releaseUnseen(world, seen);
600
+ if (world.instances.size > 0) {
601
+ leavingTheEngine(world);
602
+ aimInstances(world.camera);
603
+ for (const instances of world.instances.values()) drawInstances(instances, world.camera);
604
+ }
605
+ }
606
+
607
+ // What comes before the actors: the scene's nodes swapped in when the scene
608
+ // has changed, and the ground; and the two things that make every pass of a
609
+ // world one that leaves the engine, a ground-height callback and instancing.
610
+ function beginPass(world, runtime, sprites) {
611
+ const key = runtime.sceneKey ?? runtime.scenePath;
612
+ if (key !== world.scenePath) {
613
+ leavingTheEngine(world);
614
+ swapSceneNodes(world, key, runtime.residentScenes);
615
+ }
616
+ const setting = runtime.data?.ground;
617
+ if (!groundIsDressed(world, setting, sprites)) {
618
+ leavingTheEngine(world);
619
+ syncGround(world, setting, sprites);
620
+ }
621
+ if (typeof world.scene.userData.groundHeight === 'function' || world.instanceModels || world.instances.size > 0) {
622
+ leavingTheEngine(world);
623
+ }
624
+ }
625
+
626
+ // Whether `syncGround` would find the ground as it left it and do nothing:
627
+ // its own test, asked before calling it.
628
+ function groundIsDressed(world, setting, sprites) {
629
+ return `${JSON.stringify(setting ?? null)}|${artRefSignature(setting?.art, sprites)}` === world.groundSig;
630
+ }
631
+
632
+ // One actor's node, found or built, put where its Transform says, and ready
633
+ // to be animated: the skipping way while the pass is alone, `syncActors`'s way
634
+ // once it is not.
635
+ function placeActor(world, actor, t, sprites, files, started) {
636
+ const alone = world.generation === started;
637
+ const entry = alone ? nodeFor(world, actor, sprites, files) : nodeAsMain(world, actor, sprites, files);
638
+ const node = entry.node;
639
+ node.position.set(t.x, t.y, t.z);
640
+ const quat = actor.runtime?.quat;
641
+ if (world.generation === started) turnNode(snapshotOf(world, entry), node, t, quat);
642
+ else if (quat) node.quaternion.set(quat.x, quat.y, quat.z, quat.w);
643
+ else node.rotation.set(t.rotationX * DEG, t.rotationY * DEG, t.rotationZ * DEG);
644
+ // A node moved under something with a ground-height callback of its own,
645
+ // which animating it is about to call.
646
+ if (node.parent !== world.scene && typeof node.parent?.userData?.groundHeight === 'function') {
647
+ leavingTheEngine(world);
648
+ }
649
+ return entry;
650
+ }
651
+
652
+ function releaseUnseen(world, seen) {
653
+ for (const [id, entry] of world.nodes) {
654
+ if (seen.has(id)) continue;
655
+ releaseNode(world, entry);
656
+ world.nodes.delete(id);
657
+ }
658
+ }
659
+
660
+ // `releaseActorNode`, from a skipping pass.
661
+ function releaseNode(world, entry) {
662
+ leavingTheEngine(world);
663
+ entry.node.computedFrom = null;
664
+ releaseActorNode(world, entry);
665
+ }
666
+
667
+ // The signature suffix for a Model component's file: `actorModelSig`'s, for an
668
+ // actor placing that file.
669
+ function modelFileSig(file, sprites, files) {
670
+ return actorModelSig({ components: { Model: { file } } }, sprites, files);
671
+ }
672
+
673
+ // `modelFileSig`, built once and then handed back for as long as everything it
674
+ // was read from reads the same: the file's text, the text of every model it
675
+ // references, each art object those name and whether it has loaded, and the
676
+ // look switch. The reads are written down as the signature is built
677
+ // (`recordReads`) and made again to check it. Actors placing one file share
678
+ // the answer, and within one pass over the actors (one `sprites`, one `files`)
679
+ // it is checked once (`sigEpoch`): it is asked for only while the pass is
680
+ // alone, so nothing outside the engine has run since that check. The tables
681
+ // themselves are not kept, and what is kept is dropped whenever a pass is not
682
+ // alone, when the world is disposed, and past MODEL_SIGS_LIMIT files.
683
+ function modelSigOf(world, file, sprites, files) {
684
+ if (!file) return '';
685
+ let memo = world.modelSigs.get(file);
686
+ if (memo && memo.epoch === world.sigEpoch) return memo.sig;
687
+ if (!memo || !readsTheSame(memo, sprites, files)) {
688
+ const fileReads = [];
689
+ const artReads = [];
690
+ const look = lookIsEnabled();
691
+ const sig = modelFileSig(file, recordReads(sprites, artReads), recordReads(files, fileReads));
692
+ memo = { sig, look, fileReads, artReads: withReadiness(artReads), epoch: 0 };
693
+ if (world.modelSigs.size >= MODEL_SIGS_LIMIT) world.modelSigs.clear();
694
+ world.modelSigs.set(file, memo);
695
+ }
696
+ memo.epoch = world.sigEpoch;
697
+ return memo.sig;
698
+ }
699
+
700
+ function readsTheSame(memo, sprites, files) {
701
+ if (memo.look !== lookIsEnabled()) return false;
702
+ const { fileReads } = memo;
703
+ for (let i = 0; i < fileReads.length; i += 2) {
704
+ if (files?.[fileReads[i]] !== fileReads[i + 1]) return false;
705
+ }
706
+ return artReadsTheSame(memo.artReads, sprites);
707
+ }
708
+
709
+ // `[path, art, ...]` as read, to `[path, art, ready, ...]`: an art's signature
710
+ // is which object it is and whether it has loaded.
711
+ function withReadiness(reads) {
712
+ const out = [];
713
+ for (let i = 0; i < reads.length; i += 2) {
714
+ out.push(reads[i], reads[i + 1], artReady(reads[i + 1]));
715
+ }
716
+ return out;
717
+ }
718
+
719
+ function artReadsTheSame(artReads, sprites) {
720
+ for (let i = 0; i < artReads.length; i += 3) {
721
+ const art = sprites?.[artReads[i]];
722
+ if (art !== artReads[i + 1] || artReady(art) !== artReads[i + 2]) return false;
723
+ }
724
+ return true;
725
+ }
726
+
727
+ // Whether the actor's node signature would come out as it did when `entry`
728
+ // last built it: the Shape and Model components read the same field for
729
+ // field, the art the Shape names is the same objects in the same state, and
730
+ // the model file's signature is the same.
731
+ function looksTheSame(world, entry, actor, sprites, files) {
732
+ const built = world.snapshots.get(entry)?.builtFrom;
733
+ if (!built) return false;
734
+ const components = actor.components;
735
+ const model = components.Model;
736
+ return (
737
+ sameAs(components.Shape, built.shape) &&
738
+ sameAs(model, built.model) &&
739
+ artReadsTheSame(built.artReads, sprites) &&
740
+ modelSigOf(world, model?.file, sprites, files) === built.modelSig
741
+ );
742
+ }
743
+
744
+ // `ensureActorNode` for a pass that is alone: the same signature, compared the
745
+ // same way, but only when `looksTheSame` cannot vouch for the node. A node
746
+ // that has to be built or released ends the pass's being alone first. What a
747
+ // kept node was built from is written down after the signature is compared.
748
+ function nodeFor(world, actor, sprites, files) {
749
+ const entry = world.nodes.get(actor.id);
750
+ if (entry && looksTheSame(world, entry, actor, sprites, files)) return entry;
751
+ const artReads = [];
752
+ const modelSig = modelSigOf(world, actor.components.Model?.file, sprites, files);
753
+ const sig = nodeSignature(actor, recordReads(sprites, artReads), modelSig);
754
+ if (!entry || entry.sig !== sig) {
755
+ return buildNode(world, entry, actor, sig, modelSig, sprites, files);
756
+ }
757
+ snapshotOf(world, entry).builtFrom = {
758
+ shape: remember(actor.components.Shape),
759
+ model: remember(actor.components.Model),
760
+ artReads: withReadiness(artReads),
761
+ modelSig,
762
+ };
763
+ return entry;
764
+ }
765
+
766
+ // `ensureActorNode` as it is, for a pass that is not alone: the signature is
767
+ // built and compared, nothing is read from what was written down and nothing
768
+ // is written. The node is an ActorNode all the same.
769
+ function nodeAsMain(world, actor, sprites, files) {
770
+ const modelSig = actorModelSig(actor, sprites, files);
771
+ const sig = nodeSignature(actor, sprites, modelSig);
772
+ const entry = world.nodes.get(actor.id);
773
+ if (entry && entry.sig === sig) return entry;
774
+ return buildNode(world, entry, actor, sig, modelSig, sprites, files);
775
+ }
776
+
777
+ // What is written down for an entry, made on first use.
778
+ function snapshotOf(world, entry) {
779
+ let snapshot = world.snapshots.get(entry);
780
+ if (!snapshot) {
781
+ snapshot = { builtFrom: undefined, turnedTo: null };
782
+ world.snapshots.set(entry, snapshot);
783
+ }
784
+ return snapshot;
785
+ }
786
+
787
+ function buildNode(world, old, actor, sig, modelSig, sprites, files) {
788
+ leavingTheEngine(world);
789
+ if (old) releaseNode(world, old);
790
+ const entry = { node: new ActorNode(world.skipping), sig };
791
+ entry.node.userData.actorId = actor.id;
792
+ fillNode(world, entry, actor, modelSig, sprites, files);
793
+ world.scene.add(entry.node);
794
+ world.nodes.set(actor.id, entry);
795
+ return entry;
796
+ }
797
+
798
+ function fillNode(world, entry, actor, modelSig, sprites, files) {
799
+ const { Model: placed, Shape: shape } = actor.components;
800
+ const model = placed?.file ? parseModelCached(files?.[placed.file]) : null;
801
+ if (model) {
802
+ addModelRig(world, entry, model, placed, `${placed.file}|${modelSig}`, { sprites, files });
803
+ } else if (shape) {
804
+ entry.node.add(makeShapeMesh(shape, sprites));
805
+ }
806
+ }
807
+
808
+ // The node's rotation for this frame: the body's quaternion, or the
809
+ // Transform's euler degrees. Setting a three.js euler works out its quaternion
810
+ // (six sines and cosines), so the euler is set only when that would change
811
+ // something: when the node's euler is not already these angles, or its
812
+ // quaternion is no longer the one the last set worked out from them.
813
+ function turnNode(snapshot, node, t, quat) {
814
+ const q = node.quaternion;
815
+ if (quat) {
816
+ q.set(quat.x, quat.y, quat.z, quat.w);
817
+ snapshot.turnedTo = null;
818
+ return;
819
+ }
820
+ const x = t.rotationX * DEG;
821
+ const y = t.rotationY * DEG;
822
+ const z = t.rotationZ * DEG;
823
+ const r = node.rotation;
824
+ const was = snapshot.turnedTo;
825
+ // `rotation.set(x, y, z)` stores the three angles, keeps the euler's order,
826
+ // and works the quaternion out from the angles and that order. So it would
827
+ // change nothing exactly when the angles are already these, the order is
828
+ // the one the last set worked with, and the quaternion is the one it left.
829
+ // `Object.is`, so that -0 and 0, which turn out quaternions differing in the
830
+ // sign of a zero, are not taken for each other.
831
+ if (was && r.order === was.order && sameTurn(r, x, y, z) && sameQuaternion(q, was)) return;
832
+ r.set(x, y, z);
833
+ snapshot.turnedTo = { order: r.order, x: q.x, y: q.y, z: q.z, w: q.w };
834
+ }
835
+
836
+ function sameTurn(r, x, y, z) {
837
+ return Object.is(r.x, x) && Object.is(r.y, y) && Object.is(r.z, z);
838
+ }
839
+
840
+ function sameQuaternion(q, was) {
841
+ return Object.is(q.x, was.x) && Object.is(q.y, was.y) && Object.is(q.z, was.z) && Object.is(q.w, was.w);
320
842
  }
@@ -5,7 +5,7 @@
5
5
  "scripts": {
6
6
  "restart": "castle-web restart .",
7
7
  "screenshot": "castle-web screenshot .",
8
- "check": "eslint . && jscpd && node --input-type=module -e \"const { bundleProject } = await import('castle-web-cli/dist/bundle.js'); await bundleProject('.');\""
8
+ "check": "eslint . && jscpd && node scripts/test-static-actors.mjs && node --input-type=module -e \"const { bundleProject } = await import('castle-web-cli/dist/bundle.js'); await bundleProject('.');\""
9
9
  },
10
10
  "jscpd": {
11
11
  "path": [