castle-web-cli 0.4.230 → 0.4.232

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 (92) hide show
  1. package/dist/castle-host/host.js +81 -0
  2. package/dist/devSaveStorage.d.ts +36 -0
  3. package/dist/devSaveStorage.js +469 -0
  4. package/dist/devSessionChild.js +22 -12
  5. package/dist/devSessionServer.js +8 -2
  6. package/dist/devSessionStorage.d.ts +9 -0
  7. package/dist/devSessionStorage.js +66 -1
  8. package/dist/init.js +1 -1
  9. package/dist/serve.js +5 -1
  10. package/dist/serverBundle.js +5 -3
  11. package/kits/base/castle.json +1 -1
  12. package/kits/base/sdk/README.md +148 -1
  13. package/kits/base/sdk/castle.d.ts +4 -0
  14. package/kits/base/sdk/castle.js +2 -0
  15. package/kits/base/sdk/commands.d.ts +15 -0
  16. package/kits/base/sdk/multiplayer.js +52 -4
  17. package/kits/base/sdk/save.d.ts +197 -0
  18. package/kits/base/sdk/save.js +525 -0
  19. package/kits/base/sdk/saveCoordinator.d.ts +39 -0
  20. package/kits/base/sdk/saveCoordinator.js +252 -0
  21. package/kits/base/sdk/server/storage.d.ts +3 -2
  22. package/kits/base/sdk/server/storage.js +25 -5
  23. package/kits/base/sdk/server/wrapper.d.ts +4 -0
  24. package/kits/base/sdk/server/wrapper.js +2 -0
  25. package/kits/base/sdk/store.d.ts +3 -2
  26. package/kits/base/sdk/store.js +5 -0
  27. package/kits/hub-game/CLAUDE.md +29 -4
  28. package/kits/hub-game/code/client/avatar.js +39 -0
  29. package/kits/hub-game/code/client/chat.js +12 -0
  30. package/kits/hub-game/code/client/chrome.js +237 -13
  31. package/kits/hub-game/code/client/grab.js +166 -7
  32. package/kits/hub-game/code/client/hats.js +26 -0
  33. package/kits/hub-game/code/client/hookLayer.js +36 -3
  34. package/kits/hub-game/code/client/hudClear.js +126 -0
  35. package/kits/hub-game/code/client/state.js +35 -1
  36. package/kits/hub-game/code/client/talk.js +10 -36
  37. package/kits/hub-game/code/client/tiers.js +505 -0
  38. package/kits/hub-game/code/client/together.js +144 -4
  39. package/kits/hub-game/code/client/wear.js +96 -14
  40. package/kits/hub-game/code/server/actors.js +5 -0
  41. package/kits/hub-game/code/server/grab.js +299 -13
  42. package/kits/hub-game/code/server/hub.js +162 -7
  43. package/kits/hub-game/code/server/manifest.js +80 -8
  44. package/kits/hub-game/code/server/npcs.js +21 -33
  45. package/kits/hub-game/code/server/party.js +75 -6
  46. package/kits/hub-game/code/server/say.js +8 -2
  47. package/kits/hub-game/code/server/wear.js +116 -11
  48. package/kits/hub-game/code/systems/hub.js +386 -21
  49. package/kits/hub-game/docs/contract.md +285 -19
  50. package/kits/hub-game/package.json +1 -1
  51. package/kits/hub-game/scripts/test-chat.mjs +32 -0
  52. package/kits/hub-game/scripts/test-grab-client.mjs +511 -0
  53. package/kits/hub-game/scripts/test-grab.mjs +857 -3
  54. package/kits/hub-game/scripts/test-hats.mjs +229 -0
  55. package/kits/hub-game/scripts/test-hub-trip.mjs +721 -0
  56. package/kits/hub-game/scripts/test-hud-clear.mjs +676 -0
  57. package/kits/hub-game/scripts/test-manifest.mjs +122 -1
  58. package/kits/hub-game/scripts/test-npcs.mjs +34 -24
  59. package/kits/hub-game/scripts/test-party.mjs +108 -4
  60. package/kits/hub-game/scripts/test-say.mjs +59 -2
  61. package/kits/hub-game/scripts/test-tiers.mjs +854 -0
  62. package/kits/hub-game/scripts/test-together.mjs +33 -1
  63. package/kits/hub-game/scripts/test-try-on.mjs +940 -0
  64. package/kits/physics-2d/CLAUDE.md +2 -0
  65. package/kits/physics-2d/castle.json +2 -2
  66. package/kits/physics-2d/engine/scene.js +127 -0
  67. package/kits/physics-2d/package.json +1 -1
  68. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +298 -0
  69. package/kits/physics-3d/CLAUDE.md +531 -0
  70. package/kits/physics-3d/behaviors/Player.jsx +437 -3
  71. package/kits/physics-3d/castle.json +3 -3
  72. package/kits/physics-3d/docs/pxmodel-format.md +4 -0
  73. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +33 -1
  74. package/kits/physics-3d/engine3d/actornode.js +253 -0
  75. package/kits/physics-3d/engine3d/nearshadows.js +600 -0
  76. package/kits/physics-3d/engine3d/optimize.js +49 -0
  77. package/kits/physics-3d/engine3d/orbitinput.js +277 -0
  78. package/kits/physics-3d/engine3d/unchanged.js +153 -0
  79. package/kits/physics-3d/engine3d/world3d.js +525 -11
  80. package/kits/physics-3d/package.json +1 -1
  81. package/kits/physics-3d/scripts/Player.before-orbit.mjs +310 -0
  82. package/kits/physics-3d/scripts/Scene3DPlayer.before-orbit.jsx +337 -0
  83. package/kits/physics-3d/scripts/test-camera-follow.mjs +543 -0
  84. package/kits/physics-3d/scripts/test-camera-orbit.mjs +2105 -0
  85. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +787 -0
  86. package/kits/physics-3d/scripts/test-near-shadows.mjs +1073 -0
  87. package/kits/physics-3d/scripts/test-static-actors.mjs +667 -0
  88. package/kits/physics-3d/scripts/test-static-passes.mjs +459 -0
  89. package/kits/physics-3d/scripts/test-static-physics.mjs +128 -0
  90. package/kits/physics-3d/scripts/test-steady-hover.mjs +633 -0
  91. package/kits/physics-3d/systems/physics3d.js +273 -9
  92. package/package.json +1 -1
@@ -17,11 +17,17 @@ 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,
23
28
  copyModel,
24
29
  isStaticModel,
30
+ dropEmptyGroups,
25
31
  makeInstances,
26
32
  drawInstances,
27
33
  aimInstances,
@@ -83,6 +89,21 @@ export function makeWorld3D(canvas) {
83
89
  scenePath: undefined,
84
90
  parked: new Map(),
85
91
  models: new Map(),
92
+ // For scenes that set `"engine": { "skipUnchangedActors": true }`
93
+ // (`syncActorsSkipping`): whether the scene now playing is one, each model
94
+ // file's signature with what it was read from, and the counts that say
95
+ // when those are due a check.
96
+ skipping: { on: false },
97
+ modelSigs: new Map(),
98
+ sigEpoch: 0,
99
+ syncCount: 0,
100
+ syncDepth: 0,
101
+ generation: 0,
102
+ snapshots: new WeakMap(),
103
+ // For scenes that set `"engine": { "shadows": { "distance": n } }`
104
+ // (nearshadows.js): the shadow the engine draws for them, which is its
105
+ // own; the sun's is never written.
106
+ nearShadows: null,
86
107
  instances: new Map(),
87
108
  instanceModels: false,
88
109
  debugLines,
@@ -179,9 +200,9 @@ function actorModelSig(actor, sprites, files) {
179
200
  // Build / refresh the node for one actor. Rebuilds only when what it looks
180
201
  // like (Shape / Model / their art) changes. A Model replaces the Shape's own
181
202
  // mesh with the .pxmodel rig; the Shape still sizes the physics collider.
182
- function ensureActorNode(world, actor, sprites, files) {
203
+ function ensureActorNode(world, actor, sprites, files, drops) {
183
204
  const modelSig = actorModelSig(actor, sprites, files);
184
- const sig = nodeSignature(actor, sprites, modelSig);
205
+ const sig = builtAs(drops, nodeSignature(actor, sprites, modelSig));
185
206
  let entry = world.nodes.get(actor.id);
186
207
  if (entry && entry.sig !== sig) {
187
208
  releaseActorNode(world, entry);
@@ -198,6 +219,7 @@ function ensureActorNode(world, actor, sprites, files) {
198
219
  addModelRig(world, entry, model, modelComponent, `${modelComponent.file}|${modelSig}`, {
199
220
  sprites,
200
221
  files,
222
+ drops,
201
223
  });
202
224
  } else if (shape) {
203
225
  node.add(makeShapeMesh(shape, sprites));
@@ -210,12 +232,18 @@ function ensureActorNode(world, actor, sprites, files) {
210
232
 
211
233
  // The actor's model, from the shared build of it: a copy of its own, or,
212
234
  // for a static model in the player, a place among that model's instances.
213
- function addModelRig(world, entry, model, modelComponent, key, { sprites, files }) {
235
+ function addModelRig(world, entry, model, modelComponent, key, { sprites, files, drops }) {
214
236
  const file = modelComponent.file;
237
+ if (drops === true) key = `${key}|dropEmptyParts`;
215
238
  entry.modelKey = key;
216
239
  const template = takeModel(world.models, key, () =>
217
240
  buildModelNode(model, sprites, files, file, [file], { optimize: true })
218
241
  );
242
+ if (drops === true && withoutEmptyParts(template, model).children.length === 0) {
243
+ // A model that draws nothing has no rig; `modelParts` is there and empty.
244
+ entry.node.userData.modelParts = new Map();
245
+ return;
246
+ }
219
247
  const instanced = world.instanceModels && isStaticModel(template);
220
248
  const rig = instanced ? new THREE.Group() : copyModel(template);
221
249
  rig.position.y = modelComponent.yOffset ?? 0;
@@ -232,6 +260,51 @@ function addModelRig(world, entry, model, modelComponent, key, { sprites, files
232
260
  }
233
261
  }
234
262
 
263
+ //
264
+ // Scenes that set `"engine": { "dropEmptyParts": true }`
265
+ //
266
+ // A game build merges a model's meshes into a few draw calls and leaves the
267
+ // group of every part standing, most of them now empty; a town's scene is two
268
+ // thirds such groups, each visited by three.js and by the engine on every
269
+ // frame. For a scene that asks, a placed model is built without the groups
270
+ // that draw nothing (optimize.js `dropEmptyGroups` has what goes and what
271
+ // always stays), and an actor whose model draws nothing at all gets no rig
272
+ // under its node. CLAUDE.md has the terms.
273
+ //
274
+ // With the key absent nothing here runs but the tests of `drops`: a node's
275
+ // signature, a shared build's key and the build are what they were. With it,
276
+ // the signature and the key say so, so that a node or a build made for a
277
+ // scene that asked is never one for a scene that did not, in either
278
+ // direction: the nodes of a resident scene parked while another plays, a pack
279
+ // mounted in a town, a door trip, a scene file reloaded with the key changed.
280
+ //
281
+ // Whether a pass drops is the pass's own: `syncActors` reads it once from the
282
+ // runtime it was handed and passes it down (`drops`) to everything that makes
283
+ // a signature or a build. Nothing about it is kept on the world, so a pass
284
+ // entered from inside another (a callback that syncs another scene), one that
285
+ // throws, or a dispose, cannot change what the pass around it builds. What is
286
+ // kept says which way it was made and is only ever matched against the pass
287
+ // asking: a node's `sig`, a shared build's key (and so `world.instances`,
288
+ // keyed the same), and what a skipping pass wrote down (`builtFrom.drops`).
289
+
290
+ // The shared builds whose empty groups have been taken out.
291
+ const withoutEmpty = new WeakSet();
292
+
293
+ // `template`, a shared build made for such a scene, with its empty groups
294
+ // gone: taken out once, when the build is first placed.
295
+ function withoutEmptyParts(template, model) {
296
+ if (!withoutEmpty.has(template)) {
297
+ withoutEmpty.add(template);
298
+ dropEmptyGroups(template, model);
299
+ }
300
+ return template;
301
+ }
302
+
303
+ // A node's signature, saying which way it was built.
304
+ function builtAs(drops, sig) {
305
+ return drops === true ? `${sig}|dropEmptyParts` : sig;
306
+ }
307
+
235
308
  // Removes an actor's node. A shared model build is given back rather than
236
309
  // disposed, since other actors may still draw it.
237
310
  function releaseActorNode(world, entry) {
@@ -258,6 +331,12 @@ const DEG = Math.PI / 180;
258
331
  // `actor.runtime.quat`; everything else rotates by the Transform's euler
259
332
  // degrees.
260
333
  export function syncActors(world, runtime, sprites, dt = 0) {
334
+ const drops = runtime.dropsEmptyParts === true;
335
+ if (runtime.skipsUnchangedActors === true && world.disposed !== true) {
336
+ syncActorsSkipping(world, runtime, sprites, dt, drops);
337
+ return;
338
+ }
339
+ if (world.skipping.on) stopSkipping(world);
261
340
  // A scene is keyed by its content as well as its path (`sceneKey`), so a
262
341
  // town and a mounted game that both call theirs `scenes/main.scene` are
263
342
  // different scenes here.
@@ -271,7 +350,7 @@ export function syncActors(world, runtime, sprites, dt = 0) {
271
350
  const t = actor.components.Transform;
272
351
  if (!t) continue;
273
352
  seen.add(actor.id);
274
- const entry = ensureActorNode(world, actor, sprites, runtime.files);
353
+ const entry = ensureActorNode(world, actor, sprites, runtime.files, drops);
275
354
  const node = entry.node;
276
355
  node.position.set(t.x, t.y, t.z);
277
356
  const quat = actor.runtime?.quat;
@@ -345,7 +424,26 @@ export function resizeWorld(world, width, height) {
345
424
  world.camera.updateProjectionMatrix();
346
425
  }
347
426
 
348
- export function renderWorld(world) {
427
+ // `runtime` is given by the player, whose scene may have asked for shadows
428
+ // near the view only (`"engine": { "shadows": { "distance": n } }`,
429
+ // nearshadows.js). The editors give none and draw every scene the one way.
430
+ export function renderWorld(world, runtime) {
431
+ // A world with nothing of the mode's, whose scene did not ask (or which is
432
+ // being disposed): the two statements this function always was.
433
+ const distance = runtime?.nearShadowDistance ?? 0;
434
+ if (!world.nearShadows && !(distance > 0 && world.disposed !== true)) {
435
+ drawWorld(world);
436
+ return;
437
+ }
438
+ renderWithNearShadows(
439
+ world,
440
+ distance,
441
+ () => fitShadowBias(world),
442
+ () => world.composer.render()
443
+ );
444
+ }
445
+
446
+ function drawWorld(world) {
349
447
  fitShadowBias(world);
350
448
  world.composer.render();
351
449
  }
@@ -374,11 +472,427 @@ function fitShadowBias(world) {
374
472
  }
375
473
 
376
474
  export function disposeWorld(world) {
377
- for (const entry of world.nodes.values()) releaseActorNode(world, entry);
378
- world.nodes.clear();
379
- for (const parked of world.parked.values()) {
380
- for (const entry of parked.values()) releaseActorNode(world, entry);
475
+ // Releasing a node runs `dispose` listeners, which may sync this world
476
+ // again. From here on it never skips (`syncActors` reads `disposed`), so
477
+ // such a sync writes nothing down; what was written down before goes now,
478
+ // and again after the listeners have run, whether or not one throws.
479
+ world.disposed = true;
480
+ // A `dispose` listener on the near-shadow mode's map that throws does not
481
+ // keep the rest from being released.
482
+ try {
483
+ dropNearShadows(world);
484
+ } finally {
485
+ disposeNodes(world);
486
+ }
487
+ }
488
+
489
+ function disposeNodes(world) {
490
+ world.skipping.on = false;
491
+ leavingTheEngine(world);
492
+ forgetEverything(world);
493
+ try {
494
+ for (const entry of world.nodes.values()) releaseActorNode(world, entry);
495
+ world.nodes.clear();
496
+ for (const parked of world.parked.values()) {
497
+ for (const entry of parked.values()) releaseActorNode(world, entry);
498
+ }
499
+ world.parked.clear();
500
+ world.renderer.dispose();
501
+ } finally {
502
+ forgetEverything(world);
503
+ }
504
+ }
505
+
506
+ //
507
+ // Scenes that set `"engine": { "skipUnchangedActors": true }`
508
+ //
509
+ // `syncActors` for such a scene. It draws what `syncActors` draws; what it
510
+ // leaves out is building, for every actor on every frame, a signature whose
511
+ // inputs read as they did when the node was built, and (in ActorNode)
512
+ // recomputing matrices nothing has moved.
513
+ //
514
+ // The rule it is built to:
515
+ //
516
+ // Fast-path state (snapshots, pass marks, cached signatures) is trusted only
517
+ // across a span in which no code outside the engine has run. A pass in which
518
+ // the engine calls out (any callback), is re-entered, or sees the scene
519
+ // change, finishes exactly as main would and leaves no fast-path state
520
+ // behind.
521
+ //
522
+ // How: `world.generation` moves whenever code outside the engine may run inside
523
+ // a pass, and `world.syncDepth` says whether a pass is already running. A pass
524
+ // notes the generation it started at and looks again before each actor; once
525
+ // it has moved, the rest of the pass does for each actor what `syncActors`
526
+ // does (the signature built and compared, the rotation set) and writes nothing
527
+ // down, and when the outermost pass ends everything written down before is
528
+ // dropped. It is dropped as well when the outermost pass ends by throwing,
529
+ // whatever the generation says. A pass entered while another is running starts
530
+ // that way. There are no marks on entries: each pass has its own `seen`, as
531
+ // `syncActors` has.
532
+ //
533
+ // The generation is moved in one place, `leavingTheEngine`, called BEFORE the
534
+ // engine does anything in a pass that can run someone else's code. Nothing is
535
+ // inferred afterwards from what changed. three.js runs listeners
536
+ // (EventDispatcher) from `add`, `remove`, `removeFromParent`, `clear` and
537
+ // `attach` on an object (`added`, `removed`, `childadded`, `childremoved`) and
538
+ // from `dispose` on a geometry, material, texture or render target. A pass
539
+ // reaches those through, and only through:
540
+ // - `swapSceneNodes` (a scene change: nodes added, removed, released);
541
+ // - `syncGround` when the ground's signature differs (the old material
542
+ // disposed), asked beforehand by `groundIsDressed`;
543
+ // - `buildNode` (a node built: its old one released, the new one added, and
544
+ // for an instanced model `makeInstances`);
545
+ // - `releaseNode` (a node removed, its meshes disposed, `removeInstances`);
546
+ // - `drawInstances` (an instanced mesh replaced: removed, disposed, added).
547
+ // Whether it will replace one is its own business, so a world that has
548
+ // instances runs every pass main's way from the start;
549
+ // and it calls a deck's function in one place:
550
+ // - `scene.userData.groundHeight` (motion.js `airSpeed`), while a walking
551
+ // model's parts are animated. A scene that has one runs every pass main's
552
+ // way from the start; a node moved under something else that has one moves
553
+ // the generation before that node is animated.
554
+ // `syncActors` called from any of those, keyed or not, is the re-entry.
555
+ // Building a model (`takeModel`, `buildModelNode`, `copyModel`, `fillNode`)
556
+ // adds to objects that were made a moment ago and that nothing can be
557
+ // listening to; it happens inside `buildNode` regardless. Nothing else in a
558
+ // pass leaves the engine: reading plain components and the deck's `sprites`
559
+ // and `files` tables, `runtime.getActors`, three.js math, and building
560
+ // signatures from plain data (`JSON.stringify` calls no one for those). A
561
+ // scene whose components are not plain stored data is outside the key's terms
562
+ // (CLAUDE.md).
563
+ //
564
+ // What is written down, and where:
565
+ // - `world.snapshots`, a WeakMap from a node entry to what the node was built
566
+ // from (the Shape and Model as remembered, the art read, the model
567
+ // signature) and how it was last turned. Dropped by putting a new WeakMap
568
+ // in its place. An entry that is released, or held by someone else, holds
569
+ // none of it.
570
+ // - `world.modelSigs`, a Map from a model file to its signature and the reads
571
+ // it was built from. Cleared.
572
+ // - `world.sigEpoch`, `world.syncCount`, `world.generation`, `world.syncDepth`,
573
+ // `world.skipping.on`: numbers and a flag.
574
+ // - on an ActorNode, `computedFrom`: numbers only (actornode.js), so it can
575
+ // hold nothing; cleared when its node is released, when the world leaves
576
+ // the skipping path or is disposed, and by the node itself when it finds
577
+ // the switch off.
578
+ // Snapshots are kept from one pass to the next, across which deck code does
579
+ // run; they are not trusted there but read against the live components and
580
+ // node on every use.
581
+
582
+ // How many model files' signatures are kept before the lot is dropped and
583
+ // built again as needed.
584
+ const MODEL_SIGS_LIMIT = 512;
585
+
586
+ // Called before the engine, inside a pass, does anything that can run code
587
+ // that is not the engine's. See the list above.
588
+ function leavingTheEngine(world) {
589
+ world.generation += 1;
590
+ }
591
+
592
+ // The scene now playing did not ask: every node is a plain Group again and
593
+ // nothing read from the scene that did is kept. If a pass of a scene that did
594
+ // ask is running underneath (this sync was called from inside it), it is told.
595
+ function stopSkipping(world) {
596
+ world.skipping.on = false;
597
+ leavingTheEngine(world);
598
+ forgetEverything(world);
599
+ }
600
+
601
+ // Drops everything a skipping pass wrote down about the scene.
602
+ function forgetSnapshots(world) {
603
+ world.snapshots = new WeakMap();
604
+ world.modelSigs.clear();
605
+ }
606
+
607
+ // And what each node, playing or parked, remembers of its own matrices.
608
+ function forgetEverything(world) {
609
+ forgetSnapshots(world);
610
+ const forget = (entry) => {
611
+ if (entry.node.computedFrom) entry.node.computedFrom = null;
612
+ };
613
+ world.nodes.forEach(forget);
614
+ for (const parked of world.parked.values()) parked.forEach(forget);
615
+ }
616
+
617
+ function syncActorsSkipping(world, runtime, sprites, dt, drops) {
618
+ // Entered while a pass is running: that pass is no longer alone.
619
+ if (world.syncDepth > 0) leavingTheEngine(world);
620
+ const outermost = world.syncDepth === 0;
621
+ const started = world.generation;
622
+ world.skipping.on = true;
623
+ world.syncDepth += 1;
624
+ let finished = false;
625
+ try {
626
+ skippingPass(world, runtime, sprites, dt, outermost ? started : -1, drops);
627
+ finished = true;
628
+ } finally {
629
+ world.syncDepth -= 1;
630
+ if (outermost && (!finished || world.generation !== started)) forgetSnapshots(world);
631
+ }
632
+ }
633
+
634
+ // One pass. `started` is the generation it may trust its state at; a pass
635
+ // entered inside another is given one that never matches.
636
+ function skippingPass(world, runtime, sprites, dt, started, drops) {
637
+ beginPass(world, runtime, sprites);
638
+ if (world.generation === started) {
639
+ world.syncCount += 1;
640
+ world.sigEpoch += 1;
641
+ }
642
+ const seen = new Set();
643
+ for (const actor of runtime.getActors()) {
644
+ const t = actor.components.Transform;
645
+ if (!t) continue;
646
+ seen.add(actor.id);
647
+ const entry = placeActor(world, actor, t, sprites, runtime.files, started, drops);
648
+ animateModelParts(entry, dt);
649
+ animateMotion(entry, dt, actor);
650
+ }
651
+ // While the pass was alone every actor seen has its node and no node was
652
+ // released, so as many nodes as actors seen means no node has lost its actor.
653
+ if (world.generation !== started || seen.size !== world.nodes.size) releaseUnseen(world, seen);
654
+ if (world.instances.size > 0) {
655
+ leavingTheEngine(world);
656
+ aimInstances(world.camera);
657
+ for (const instances of world.instances.values()) drawInstances(instances, world.camera);
658
+ }
659
+ }
660
+
661
+ // What comes before the actors: the scene's nodes swapped in when the scene
662
+ // has changed, and the ground; and the two things that make every pass of a
663
+ // world one that leaves the engine, a ground-height callback and instancing.
664
+ function beginPass(world, runtime, sprites) {
665
+ const key = runtime.sceneKey ?? runtime.scenePath;
666
+ if (key !== world.scenePath) {
667
+ leavingTheEngine(world);
668
+ swapSceneNodes(world, key, runtime.residentScenes);
669
+ }
670
+ const setting = runtime.data?.ground;
671
+ if (!groundIsDressed(world, setting, sprites)) {
672
+ leavingTheEngine(world);
673
+ syncGround(world, setting, sprites);
674
+ }
675
+ if (typeof world.scene.userData.groundHeight === 'function' || world.instanceModels || world.instances.size > 0) {
676
+ leavingTheEngine(world);
381
677
  }
382
- world.parked.clear();
383
- world.renderer.dispose();
678
+ }
679
+
680
+ // Whether `syncGround` would find the ground as it left it and do nothing:
681
+ // its own test, asked before calling it.
682
+ function groundIsDressed(world, setting, sprites) {
683
+ return `${JSON.stringify(setting ?? null)}|${artRefSignature(setting?.art, sprites)}` === world.groundSig;
684
+ }
685
+
686
+ // One actor's node, found or built, put where its Transform says, and ready
687
+ // to be animated: the skipping way while the pass is alone, `syncActors`'s way
688
+ // once it is not.
689
+ function placeActor(world, actor, t, sprites, files, started, drops) {
690
+ const alone = world.generation === started;
691
+ const entry = alone ? nodeFor(world, actor, sprites, files, drops) : nodeAsMain(world, actor, sprites, files, drops);
692
+ const node = entry.node;
693
+ node.position.set(t.x, t.y, t.z);
694
+ const quat = actor.runtime?.quat;
695
+ if (world.generation === started) turnNode(snapshotOf(world, entry), node, t, quat);
696
+ else if (quat) node.quaternion.set(quat.x, quat.y, quat.z, quat.w);
697
+ else node.rotation.set(t.rotationX * DEG, t.rotationY * DEG, t.rotationZ * DEG);
698
+ // A node moved under something with a ground-height callback of its own,
699
+ // which animating it is about to call.
700
+ if (node.parent !== world.scene && typeof node.parent?.userData?.groundHeight === 'function') {
701
+ leavingTheEngine(world);
702
+ }
703
+ return entry;
704
+ }
705
+
706
+ function releaseUnseen(world, seen) {
707
+ for (const [id, entry] of world.nodes) {
708
+ if (seen.has(id)) continue;
709
+ releaseNode(world, entry);
710
+ world.nodes.delete(id);
711
+ }
712
+ }
713
+
714
+ // `releaseActorNode`, from a skipping pass.
715
+ function releaseNode(world, entry) {
716
+ leavingTheEngine(world);
717
+ entry.node.computedFrom = null;
718
+ releaseActorNode(world, entry);
719
+ }
720
+
721
+ // The signature suffix for a Model component's file: `actorModelSig`'s, for an
722
+ // actor placing that file.
723
+ function modelFileSig(file, sprites, files) {
724
+ return actorModelSig({ components: { Model: { file } } }, sprites, files);
725
+ }
726
+
727
+ // `modelFileSig`, built once and then handed back for as long as everything it
728
+ // was read from reads the same: the file's text, the text of every model it
729
+ // references, each art object those name and whether it has loaded, and the
730
+ // look switch. The reads are written down as the signature is built
731
+ // (`recordReads`) and made again to check it. Actors placing one file share
732
+ // the answer, and within one pass over the actors (one `sprites`, one `files`)
733
+ // it is checked once (`sigEpoch`): it is asked for only while the pass is
734
+ // alone, so nothing outside the engine has run since that check. The tables
735
+ // themselves are not kept, and what is kept is dropped whenever a pass is not
736
+ // alone, when the world is disposed, and past MODEL_SIGS_LIMIT files.
737
+ function modelSigOf(world, file, sprites, files) {
738
+ if (!file) return '';
739
+ let memo = world.modelSigs.get(file);
740
+ if (memo && memo.epoch === world.sigEpoch) return memo.sig;
741
+ if (!memo || !readsTheSame(memo, sprites, files)) {
742
+ const fileReads = [];
743
+ const artReads = [];
744
+ const look = lookIsEnabled();
745
+ const sig = modelFileSig(file, recordReads(sprites, artReads), recordReads(files, fileReads));
746
+ memo = { sig, look, fileReads, artReads: withReadiness(artReads), epoch: 0 };
747
+ if (world.modelSigs.size >= MODEL_SIGS_LIMIT) world.modelSigs.clear();
748
+ world.modelSigs.set(file, memo);
749
+ }
750
+ memo.epoch = world.sigEpoch;
751
+ return memo.sig;
752
+ }
753
+
754
+ function readsTheSame(memo, sprites, files) {
755
+ if (memo.look !== lookIsEnabled()) return false;
756
+ const { fileReads } = memo;
757
+ for (let i = 0; i < fileReads.length; i += 2) {
758
+ if (files?.[fileReads[i]] !== fileReads[i + 1]) return false;
759
+ }
760
+ return artReadsTheSame(memo.artReads, sprites);
761
+ }
762
+
763
+ // `[path, art, ...]` as read, to `[path, art, ready, ...]`: an art's signature
764
+ // is which object it is and whether it has loaded.
765
+ function withReadiness(reads) {
766
+ const out = [];
767
+ for (let i = 0; i < reads.length; i += 2) {
768
+ out.push(reads[i], reads[i + 1], artReady(reads[i + 1]));
769
+ }
770
+ return out;
771
+ }
772
+
773
+ function artReadsTheSame(artReads, sprites) {
774
+ for (let i = 0; i < artReads.length; i += 3) {
775
+ const art = sprites?.[artReads[i]];
776
+ if (art !== artReads[i + 1] || artReady(art) !== artReads[i + 2]) return false;
777
+ }
778
+ return true;
779
+ }
780
+
781
+ // Whether the actor's node signature would come out as it did when `entry`
782
+ // last built it: the Shape and Model components read the same field for
783
+ // field, the art the Shape names is the same objects in the same state, and
784
+ // the model file's signature is the same; and it was written down by a pass
785
+ // that built the way this one does (`drops`).
786
+ function looksTheSame(world, entry, actor, sprites, files, drops) {
787
+ const built = world.snapshots.get(entry)?.builtFrom;
788
+ if (!built || built.drops !== drops) return false;
789
+ const components = actor.components;
790
+ const model = components.Model;
791
+ return (
792
+ sameAs(components.Shape, built.shape) &&
793
+ sameAs(model, built.model) &&
794
+ artReadsTheSame(built.artReads, sprites) &&
795
+ modelSigOf(world, model?.file, sprites, files) === built.modelSig
796
+ );
797
+ }
798
+
799
+ // `ensureActorNode` for a pass that is alone: the same signature, compared the
800
+ // same way, but only when `looksTheSame` cannot vouch for the node. A node
801
+ // that has to be built or released ends the pass's being alone first. What a
802
+ // kept node was built from is written down after the signature is compared.
803
+ function nodeFor(world, actor, sprites, files, drops) {
804
+ const entry = world.nodes.get(actor.id);
805
+ if (entry && looksTheSame(world, entry, actor, sprites, files, drops)) return entry;
806
+ const artReads = [];
807
+ const modelSig = modelSigOf(world, actor.components.Model?.file, sprites, files);
808
+ const sig = builtAs(drops, nodeSignature(actor, recordReads(sprites, artReads), modelSig));
809
+ if (!entry || entry.sig !== sig) {
810
+ return buildNode(world, entry, actor, sig, modelSig, sprites, files, drops);
811
+ }
812
+ snapshotOf(world, entry).builtFrom = {
813
+ shape: remember(actor.components.Shape),
814
+ model: remember(actor.components.Model),
815
+ artReads: withReadiness(artReads),
816
+ modelSig,
817
+ drops,
818
+ };
819
+ return entry;
820
+ }
821
+
822
+ // `ensureActorNode` as it is, for a pass that is not alone: the signature is
823
+ // built and compared, nothing is read from what was written down and nothing
824
+ // is written. The node is an ActorNode all the same.
825
+ function nodeAsMain(world, actor, sprites, files, drops) {
826
+ const modelSig = actorModelSig(actor, sprites, files);
827
+ const sig = builtAs(drops, nodeSignature(actor, sprites, modelSig));
828
+ const entry = world.nodes.get(actor.id);
829
+ if (entry && entry.sig === sig) return entry;
830
+ return buildNode(world, entry, actor, sig, modelSig, sprites, files, drops);
831
+ }
832
+
833
+ // What is written down for an entry, made on first use.
834
+ function snapshotOf(world, entry) {
835
+ let snapshot = world.snapshots.get(entry);
836
+ if (!snapshot) {
837
+ snapshot = { builtFrom: undefined, turnedTo: null };
838
+ world.snapshots.set(entry, snapshot);
839
+ }
840
+ return snapshot;
841
+ }
842
+
843
+ function buildNode(world, old, actor, sig, modelSig, sprites, files, drops) {
844
+ leavingTheEngine(world);
845
+ if (old) releaseNode(world, old);
846
+ const entry = { node: new ActorNode(world.skipping), sig };
847
+ entry.node.userData.actorId = actor.id;
848
+ fillNode(world, entry, actor, modelSig, sprites, files, drops);
849
+ world.scene.add(entry.node);
850
+ world.nodes.set(actor.id, entry);
851
+ return entry;
852
+ }
853
+
854
+ function fillNode(world, entry, actor, modelSig, sprites, files, drops) {
855
+ const { Model: placed, Shape: shape } = actor.components;
856
+ const model = placed?.file ? parseModelCached(files?.[placed.file]) : null;
857
+ if (model) {
858
+ addModelRig(world, entry, model, placed, `${placed.file}|${modelSig}`, { sprites, files, drops });
859
+ } else if (shape) {
860
+ entry.node.add(makeShapeMesh(shape, sprites));
861
+ }
862
+ }
863
+
864
+ // The node's rotation for this frame: the body's quaternion, or the
865
+ // Transform's euler degrees. Setting a three.js euler works out its quaternion
866
+ // (six sines and cosines), so the euler is set only when that would change
867
+ // something: when the node's euler is not already these angles, or its
868
+ // quaternion is no longer the one the last set worked out from them.
869
+ function turnNode(snapshot, node, t, quat) {
870
+ const q = node.quaternion;
871
+ if (quat) {
872
+ q.set(quat.x, quat.y, quat.z, quat.w);
873
+ snapshot.turnedTo = null;
874
+ return;
875
+ }
876
+ const x = t.rotationX * DEG;
877
+ const y = t.rotationY * DEG;
878
+ const z = t.rotationZ * DEG;
879
+ const r = node.rotation;
880
+ const was = snapshot.turnedTo;
881
+ // `rotation.set(x, y, z)` stores the three angles, keeps the euler's order,
882
+ // and works the quaternion out from the angles and that order. So it would
883
+ // change nothing exactly when the angles are already these, the order is
884
+ // the one the last set worked with, and the quaternion is the one it left.
885
+ // `Object.is`, so that -0 and 0, which turn out quaternions differing in the
886
+ // sign of a zero, are not taken for each other.
887
+ if (was && r.order === was.order && sameTurn(r, x, y, z) && sameQuaternion(q, was)) return;
888
+ r.set(x, y, z);
889
+ snapshot.turnedTo = { order: r.order, x: q.x, y: q.y, z: q.z, w: q.w };
890
+ }
891
+
892
+ function sameTurn(r, x, y, z) {
893
+ return Object.is(r.x, x) && Object.is(r.y, y) && Object.is(r.z, z);
894
+ }
895
+
896
+ function sameQuaternion(q, was) {
897
+ 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);
384
898
  }
@@ -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": [