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
@@ -0,0 +1,667 @@
1
+ // What the engine skips for an actor that did not change, in a scene that set
2
+ // `"engine": { "skipUnchangedActors": true }`, checked against doing it every
3
+ // frame:
4
+ //
5
+ // - `engine3d/actornode.js`: a tree under an ActorNode and the same tree under
6
+ // a plain THREE.Group are put through the same random edits, by every hand
7
+ // that edits a node (position, rotation, quaternion and scale of any object;
8
+ // children added, removed, moved to another parent and back, reordered; the
9
+ // parent moved; a transform changed, used and put back; a world matrix
10
+ // written directly; objects that keep their own matrices), and after every
11
+ // `updateMatrixWorld` each object's local and world matrix must be equal
12
+ // bit for bit, on the frame of the edit.
13
+ // - `engine3d/unchanged.js`: `sameAs(value, remember(value))` may say yes only
14
+ // when `JSON.stringify(value)` is what it was, through random in-place
15
+ // edits of nested component-like values, and never for a value that
16
+ // computes what it hands out.
17
+ //
18
+ // The cases a review of the first version broke are each here by name.
19
+ // `npm run check` runs it. node scripts/test-static-actors.mjs [seed]
20
+ import assert from 'node:assert/strict';
21
+ import * as THREE from 'three';
22
+ import { ActorNode } from '../engine3d/actornode.js';
23
+ import { remember, sameAs, recordReads } from '../engine3d/unchanged.js';
24
+
25
+ let seed = Number(process.argv[2] ?? 20261003) | 0;
26
+ function random() {
27
+ seed = (seed + 0x6d2b79f5) | 0;
28
+ let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
29
+ t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
30
+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
31
+ }
32
+ const pick = (list) => list[Math.floor(random() * list.length)];
33
+ const near = () => (random() - 0.5) * 8;
34
+
35
+ //
36
+ // ActorNode
37
+ //
38
+
39
+ // The same tree twice: `mine` under an ActorNode, `plain` under a Group. An
40
+ // edit is given both objects of a pair.
41
+ function makePair(parentPair) {
42
+ const pair = { mine: new THREE.Group(), plain: new THREE.Group(), children: [] };
43
+ if (parentPair) {
44
+ parentPair.mine.add(pair.mine);
45
+ parentPair.plain.add(pair.plain);
46
+ parentPair.children.push(pair);
47
+ }
48
+ return pair;
49
+ }
50
+
51
+ function makeTree() {
52
+ const scenes = { mine: new THREE.Scene(), plain: new THREE.Scene() };
53
+ const root = { mine: new ActorNode({ on: true }), plain: new THREE.Group(), children: [] };
54
+ scenes.mine.add(root.mine);
55
+ scenes.plain.add(root.plain);
56
+ const all = [root];
57
+ for (let i = 0; i < 12; i++) {
58
+ all.push(makePair(pick(all)));
59
+ }
60
+ return { scenes, root, all };
61
+ }
62
+
63
+ function assertSameMatrices(tree, what) {
64
+ const check = (pair, where) => {
65
+ assert.deepEqual(pair.mine.matrix.elements, pair.plain.matrix.elements, `${what}: local matrix of ${where}`);
66
+ assert.deepEqual(pair.mine.matrixWorld.elements, pair.plain.matrixWorld.elements, `${what}: world matrix of ${where}`);
67
+ assert.equal(pair.mine.matrixWorldNeedsUpdate, pair.plain.matrixWorldNeedsUpdate, `${what}: needsUpdate of ${where}`);
68
+ assert.equal(pair.mine.children.length, pair.plain.children.length, `${what}: children of ${where}`);
69
+ pair.children.forEach((child, i) => check(child, `${where}.${i}`));
70
+ };
71
+ check(tree.root, 'root');
72
+ }
73
+
74
+ const edits = {
75
+ nothing() {},
76
+ position(tree) {
77
+ const pair = pick(tree.all);
78
+ const [x, y, z] = [near(), near(), near()];
79
+ pair.mine.position.set(x, y, z);
80
+ pair.plain.position.set(x, y, z);
81
+ },
82
+ onePositionField(tree) {
83
+ const pair = pick(tree.all);
84
+ const y = near();
85
+ pair.mine.position.y = y;
86
+ pair.plain.position.y = y;
87
+ },
88
+ rotation(tree) {
89
+ const pair = pick(tree.all);
90
+ const [x, y, z] = [near(), near(), near()];
91
+ pair.mine.rotation.set(x, y, z);
92
+ pair.plain.rotation.set(x, y, z);
93
+ },
94
+ oneRotationField(tree) {
95
+ const pair = pick(tree.all);
96
+ const x = near();
97
+ pair.mine.rotation.x = x;
98
+ pair.plain.rotation.x = x;
99
+ },
100
+ rotationOrder(tree) {
101
+ const pair = pick(tree.all);
102
+ const order = pick(['XYZ', 'YXZ', 'ZYX']);
103
+ pair.mine.rotation.order = order;
104
+ pair.plain.rotation.order = order;
105
+ },
106
+ quaternion(tree) {
107
+ const pair = pick(tree.all);
108
+ const q = new THREE.Quaternion(near(), near(), near(), near()).normalize();
109
+ pair.mine.quaternion.copy(q);
110
+ pair.plain.quaternion.copy(q);
111
+ },
112
+ scale(tree) {
113
+ const pair = pick(tree.all);
114
+ const s = 0.2 + random() * 3;
115
+ pair.mine.scale.setScalar(s);
116
+ pair.plain.scale.setScalar(s);
117
+ },
118
+ lookAt(tree) {
119
+ const pair = pick(tree.all);
120
+ const [x, y, z] = [near(), near(), near()];
121
+ pair.mine.lookAt(x, y, z);
122
+ pair.plain.lookAt(x, y, z);
123
+ },
124
+ addChild(tree) {
125
+ tree.all.push(makePair(pick(tree.all)));
126
+ },
127
+ removeChild(tree) {
128
+ const pair = pick(tree.all.slice(1));
129
+ if (!pair || !pair.mine.parent) return;
130
+ const parent = tree.all.find((p) => p.children.includes(pair));
131
+ parent.mine.remove(pair.mine);
132
+ parent.plain.remove(pair.plain);
133
+ parent.children.splice(parent.children.indexOf(pair), 1);
134
+ const gone = new Set();
135
+ const walk = (p) => {
136
+ gone.add(p);
137
+ p.children.forEach(walk);
138
+ };
139
+ walk(pair);
140
+ tree.all = tree.all.filter((p) => !gone.has(p));
141
+ },
142
+ moveToOtherParent(tree) {
143
+ const pair = pick(tree.all.slice(1));
144
+ if (!pair) return;
145
+ const under = new Set();
146
+ const walk = (p) => {
147
+ under.add(p);
148
+ p.children.forEach(walk);
149
+ };
150
+ walk(pair);
151
+ const target = pick(tree.all.filter((p) => !under.has(p)));
152
+ const parent = tree.all.find((p) => p.children.includes(pair));
153
+ parent.children.splice(parent.children.indexOf(pair), 1);
154
+ target.mine.add(pair.mine);
155
+ target.plain.add(pair.plain);
156
+ target.children.push(pair);
157
+ },
158
+ reorderChildren(tree) {
159
+ const pair = pick(tree.all.filter((p) => p.children.length > 1));
160
+ if (!pair) return;
161
+ pair.children.reverse();
162
+ pair.mine.children.reverse();
163
+ pair.plain.children.reverse();
164
+ },
165
+ moveScene(tree) {
166
+ const x = near();
167
+ tree.scenes.mine.position.x = x;
168
+ tree.scenes.plain.position.x = x;
169
+ tree.scenes.mine.rotation.y = x / 3;
170
+ tree.scenes.plain.rotation.y = x / 3;
171
+ },
172
+ ownMatrix(tree) {
173
+ // An object that keeps its own matrix, as an instanced or hand-placed one does.
174
+ const pair = pick(tree.all.slice(1));
175
+ if (!pair) return;
176
+ const m = new THREE.Matrix4().makeTranslation(near(), near(), near());
177
+ for (const object of [pair.mine, pair.plain]) {
178
+ object.matrixAutoUpdate = false;
179
+ object.matrix.copy(m);
180
+ object.matrixWorldNeedsUpdate = true;
181
+ }
182
+ },
183
+ backToAuto(tree) {
184
+ const pair = pick(tree.all);
185
+ pair.mine.matrixAutoUpdate = true;
186
+ pair.plain.matrixAutoUpdate = true;
187
+ },
188
+ updateWorldMatrix(tree) {
189
+ // What a helper or a raycast does between frames.
190
+ const pair = pick(tree.all);
191
+ pair.mine.updateWorldMatrix(true, false);
192
+ pair.plain.updateWorldMatrix(true, false);
193
+ },
194
+ updateMatrix(tree) {
195
+ const pair = pick(tree.all);
196
+ pair.mine.updateMatrix();
197
+ pair.plain.updateMatrix();
198
+ },
199
+ // Review finding 2: a child under another parent between two renders, its
200
+ // matrices worked out there, and back where it was.
201
+ awayAndBack(tree) {
202
+ const pair = pick(tree.all.slice(1));
203
+ if (!pair) return;
204
+ const parent = tree.all.find((p) => p.children.includes(pair));
205
+ const index = parent.children.indexOf(pair);
206
+ for (const side of ['mine', 'plain']) {
207
+ const holder = new THREE.Group();
208
+ holder.position.set(10, 0, 0);
209
+ holder.add(pair[side]);
210
+ holder.updateMatrixWorld(true);
211
+ parent[side].children.splice(index, 0, pair[side]);
212
+ pair[side].parent = parent[side];
213
+ holder.children.length = 0;
214
+ }
215
+ },
216
+ // Review finding 2: a transform changed, its matrices worked out, and the
217
+ // transform put back.
218
+ changedUsedAndPutBack(tree) {
219
+ const pair = pick(tree.all.slice(1));
220
+ if (!pair) return;
221
+ for (const object of [pair.mine, pair.plain]) {
222
+ const x = object.position.x;
223
+ object.position.x = x + 7;
224
+ object.updateMatrixWorld(true);
225
+ object.position.x = x;
226
+ }
227
+ },
228
+ // Review finding 2: a world matrix written directly.
229
+ worldMatrixWritten(tree) {
230
+ const pair = pick(tree.all);
231
+ pair.mine.matrixWorld.elements[12] += 3;
232
+ pair.plain.matrixWorld.elements[12] += 3;
233
+ },
234
+ reparentRoot(tree) {
235
+ // The actor node itself under another moving object, and back.
236
+ const holder = tree.holder ?? (tree.holder = { mine: new THREE.Group(), plain: new THREE.Group() });
237
+ const under = tree.root.mine.parent === tree.scenes.mine;
238
+ for (const side of ['mine', 'plain']) {
239
+ if (under) {
240
+ tree.scenes[side].add(holder[side]);
241
+ holder[side].add(tree.root[side]);
242
+ holder[side].position.set(1, 2, 3);
243
+ } else {
244
+ tree.scenes[side].add(tree.root[side]);
245
+ }
246
+ }
247
+ },
248
+ };
249
+
250
+ function runTrees() {
251
+ const names = Object.keys(edits);
252
+ let frames = 0;
253
+ let skipped = 0;
254
+ for (let t = 0; t < 60; t++) {
255
+ const tree = makeTree();
256
+ for (let frame = 0; frame < 250; frame++) {
257
+ // Mostly still frames with an edit now and then, and bursts of edits.
258
+ const count = random() < 0.5 ? 0 : random() < 0.8 ? 1 : 4;
259
+ const done = [];
260
+ for (let i = 0; i < count; i++) {
261
+ const name = pick(names);
262
+ edits[name](tree);
263
+ done.push(name);
264
+ }
265
+ const before = tree.root.mine.computedFrom;
266
+ const stamp = before ? before.numbers.slice() : null;
267
+ tree.scenes.mine.updateMatrixWorld();
268
+ tree.scenes.plain.updateMatrixWorld();
269
+ assertSameMatrices(tree, `tree ${t} frame ${frame} after [${done.join(', ')}]`);
270
+ frames += 1;
271
+ if (count === 0 && stamp && tree.root.mine.computedFrom === before) skipped += 1;
272
+ }
273
+ }
274
+ return { frames, skipped };
275
+ }
276
+
277
+ // A still tree is not walked: three.js's own method is not reached.
278
+ function stillTreeIsSkipped() {
279
+ const scene = new THREE.Scene();
280
+ const node = new ActorNode({ on: true });
281
+ const child = new THREE.Mesh();
282
+ node.add(child);
283
+ scene.add(node);
284
+ let composed = 0;
285
+ const compose = THREE.Matrix4.prototype.compose;
286
+ THREE.Matrix4.prototype.compose = function (...args) {
287
+ composed += 1;
288
+ return compose.apply(this, args);
289
+ };
290
+ try {
291
+ scene.updateMatrixWorld();
292
+ const first = composed;
293
+ assert.ok(first >= 3, 'the first walk composes every object');
294
+ composed = 0;
295
+ for (let i = 0; i < 10; i++) scene.updateMatrixWorld();
296
+ assert.equal(composed, 10, 'ten still frames compose the scene alone, ten times');
297
+ child.position.x = 2;
298
+ composed = 0;
299
+ scene.updateMatrixWorld();
300
+ assert.equal(composed, 3, 'a moved child walks the whole node on that frame');
301
+ assert.equal(child.matrixWorld.elements[12], 2);
302
+ // An object with an updateMatrixWorld of its own is walked every frame.
303
+ const camera = new THREE.PerspectiveCamera();
304
+ node.add(camera);
305
+ scene.updateMatrixWorld();
306
+ composed = 0;
307
+ scene.updateMatrixWorld();
308
+ assert.equal(composed, 4, 'a node holding a camera is never skipped');
309
+ assert.equal(node.computedFrom, null);
310
+ } finally {
311
+ THREE.Matrix4.prototype.compose = compose;
312
+ }
313
+ }
314
+
315
+ // Review finding 2, each case by itself: the child ends where a plain Group
316
+ // puts it.
317
+ function staleMatricesAreSeen() {
318
+ const build = (Root) => {
319
+ const scene = new THREE.Scene();
320
+ const node = new Root({ on: true });
321
+ const child = new THREE.Group();
322
+ node.add(child);
323
+ scene.add(node);
324
+ scene.updateMatrixWorld();
325
+ return { scene, node, child };
326
+ };
327
+ const cases = {
328
+ 'moved under another parent and back'({ node, child }) {
329
+ const holder = new THREE.Group();
330
+ holder.position.x = 10;
331
+ holder.add(child);
332
+ holder.updateMatrixWorld(true);
333
+ node.add(child);
334
+ },
335
+ 'position changed, matrices updated, position put back'({ child }) {
336
+ child.position.x = 5;
337
+ child.updateMatrixWorld(true);
338
+ child.position.x = 0;
339
+ },
340
+ 'world matrix written directly'({ child }) {
341
+ child.matrixWorld.elements[12] = 10;
342
+ },
343
+ };
344
+ for (const [name, act] of Object.entries(cases)) {
345
+ const mine = build(ActorNode);
346
+ const plain = build(THREE.Group);
347
+ act(mine);
348
+ act(plain);
349
+ mine.scene.updateMatrixWorld();
350
+ plain.scene.updateMatrixWorld();
351
+ assert.deepEqual(mine.child.matrixWorld.elements, plain.child.matrixWorld.elements, name);
352
+ assert.equal(mine.child.matrixWorld.elements[12], 0, name);
353
+ }
354
+ }
355
+
356
+ // With the world's switch off, or with none, it is a Group: every frame
357
+ // computes everything and nothing is remembered.
358
+ function offIsAGroup() {
359
+ for (const skipping of [{ on: false }, null, undefined]) {
360
+ const scene = new THREE.Scene();
361
+ const node = new ActorNode(skipping);
362
+ node.add(new THREE.Mesh());
363
+ scene.add(node);
364
+ let composed = 0;
365
+ const compose = THREE.Matrix4.prototype.compose;
366
+ THREE.Matrix4.prototype.compose = function (...args) {
367
+ composed += 1;
368
+ return compose.apply(this, args);
369
+ };
370
+ try {
371
+ for (let i = 0; i < 5; i++) scene.updateMatrixWorld();
372
+ } finally {
373
+ THREE.Matrix4.prototype.compose = compose;
374
+ }
375
+ assert.equal(composed, 15, 'three objects composed on each of five frames');
376
+ assert.equal(node.computedFrom, null, 'and nothing is remembered');
377
+ }
378
+ // A node that was skipping is a Group again when the switch goes off.
379
+ const skipping = { on: true };
380
+ const scene = new THREE.Scene();
381
+ const node = new ActorNode(skipping);
382
+ const child = new THREE.Mesh();
383
+ node.add(child);
384
+ scene.add(node);
385
+ scene.updateMatrixWorld();
386
+ assert.ok(node.computedFrom);
387
+ skipping.on = false;
388
+ child.matrix.elements[12] = 99; // what three.js overwrites every frame
389
+ scene.updateMatrixWorld();
390
+ assert.equal(child.matrix.elements[12], 0);
391
+ assert.equal(node.computedFrom, null, 'off, the record is dropped');
392
+ child.position.x = 3;
393
+ scene.updateMatrixWorld();
394
+ skipping.on = true;
395
+ scene.updateMatrixWorld();
396
+ assert.equal(child.matrixWorld.elements[12], 3);
397
+ }
398
+
399
+ // What a node remembers is numbers: it refers to no object, so it can keep
400
+ // nothing alive whoever holds the node (a fifth review's case).
401
+ function recordHoldsNumbersOnly() {
402
+ const scene = new THREE.Scene();
403
+ const node = new ActorNode({ on: true });
404
+ const child = new THREE.Group();
405
+ child.add(new THREE.Mesh());
406
+ node.add(child, new THREE.Mesh());
407
+ scene.add(node);
408
+ scene.updateMatrixWorld();
409
+ const record = node.computedFrom;
410
+ assert.ok(record && record.ids.length === 4);
411
+ for (const [name, value] of Object.entries(record)) {
412
+ assert.ok(typeof value === 'number' || ArrayBuffer.isView(value), `${name} is not a number or an array of numbers`);
413
+ }
414
+ }
415
+
416
+ // It is still a Group to everything that asks.
417
+ function isAGroup() {
418
+ const node = new ActorNode({ on: true });
419
+ assert.ok(node.isGroup && node.isObject3D && node.type === 'Group');
420
+ node.position.set(1, 2, 3);
421
+ node.add(new THREE.Mesh());
422
+ const copy = node.clone();
423
+ assert.ok(copy instanceof ActorNode && copy.children.length === 1 && copy.position.y === 2);
424
+ assert.equal(copy.computedFrom, null);
425
+ }
426
+
427
+ //
428
+ // unchanged.js
429
+ //
430
+
431
+ function randomValue(depth = 0) {
432
+ const roll = random();
433
+ if (depth > 2 || roll < 0.45) {
434
+ return pick([0, 1, -1, 0.5, 2, '', 'box', '#ff0000', 'models/a.pxmodel', true, false, null, undefined, NaN]);
435
+ }
436
+ if (roll < 0.6) {
437
+ return Array.from({ length: Math.floor(random() * 4) }, () => randomValue(depth + 1));
438
+ }
439
+ const object = {};
440
+ for (const key of ['kind', 'width', 'height', 'color', 'art', 'solid', 'type', 'front'].filter(() => random() < 0.5)) {
441
+ object[key] = randomValue(depth + 1);
442
+ }
443
+ return object;
444
+ }
445
+
446
+ // One in-place edit somewhere inside `value`.
447
+ function editInPlace(value) {
448
+ const holders = [];
449
+ const walk = (v) => {
450
+ if (v && typeof v === 'object') {
451
+ holders.push(v);
452
+ for (const key of Object.keys(v)) walk(v[key]);
453
+ }
454
+ };
455
+ walk(value);
456
+ const holder = pick(holders);
457
+ if (!holder) return;
458
+ const keys = Object.keys(holder);
459
+ const roll = random();
460
+ if (Array.isArray(holder)) {
461
+ if (roll < 0.3) holder.push(randomValue(2));
462
+ else if (roll < 0.5 && holder.length) holder.pop();
463
+ else if (holder.length) holder[Math.floor(random() * holder.length)] = randomValue(2);
464
+ return;
465
+ }
466
+ if (roll < 0.25) holder[pick(['kind', 'extra', 'tint', '$enabled'])] = randomValue(2);
467
+ else if (roll < 0.45 && keys.length) delete holder[pick(keys)];
468
+ else if (roll < 0.55 && keys.length) {
469
+ // The same keys in another order.
470
+ const key = keys[0];
471
+ const kept = holder[key];
472
+ delete holder[key];
473
+ holder[key] = kept;
474
+ } else if (keys.length) holder[pick(keys)] = randomValue(2);
475
+ }
476
+
477
+ function runValues() {
478
+ let yes = 0;
479
+ let no = 0;
480
+ for (let i = 0; i < 4000; i++) {
481
+ const value = randomValue();
482
+ const text = JSON.stringify(value);
483
+ const memory = remember(value);
484
+ for (let edit = 0; edit < 6; edit++) {
485
+ if (random() < 0.6) editInPlace(value);
486
+ const same = sameAs(value, memory);
487
+ if (same) {
488
+ assert.equal(JSON.stringify(value), text, 'sameAs said yes and the signature differs');
489
+ yes += 1;
490
+ } else {
491
+ no += 1;
492
+ }
493
+ }
494
+ }
495
+ assert.ok(yes > 2000 && no > 2000, `both answers are exercised (${yes} yes, ${no} no)`);
496
+ return { yes, no };
497
+ }
498
+
499
+ function valueEdges() {
500
+ const shape = { kind: 'box', width: 1, art: { front: 'a.sprite', top: 'b.sprite' }, artRepeat: [2, 2] };
501
+ const memory = remember(shape);
502
+ assert.ok(sameAs(shape, memory), 'untouched');
503
+ shape.art.front = 'c.sprite';
504
+ assert.ok(!sameAs(shape, memory), 'a nested field');
505
+ shape.art.front = 'a.sprite';
506
+ assert.ok(sameAs(shape, memory), 'and back');
507
+ shape.artRepeat[1] = 3;
508
+ assert.ok(!sameAs(shape, memory), 'an array element');
509
+ shape.artRepeat[1] = 2;
510
+ shape.solid = undefined;
511
+ assert.ok(!sameAs(shape, memory), 'a key added, even one JSON leaves out');
512
+ delete shape.solid;
513
+ assert.ok(sameAs(shape, memory));
514
+ assert.ok(!sameAs({ ...shape }, memory), 'an equal copy is not the same object: the caller compares the string');
515
+ assert.ok(sameAs(undefined, remember(undefined)) && sameAs(null, remember(null)));
516
+ assert.ok(!sameAs(null, remember(undefined)) && !sameAs(undefined, remember(null)));
517
+ assert.ok(!sameAs(NaN, remember(NaN)), 'NaN takes the string path');
518
+ // Values JSON.stringify treats specially are never "the same".
519
+ for (const odd of [new Date(0), new Map(), { toJSON: () => 1 }, 10n, new (class Shape {})()]) {
520
+ assert.ok(!sameAs(odd, remember(odd)), `never the same: ${Object.prototype.toString.call(odd)}`);
521
+ }
522
+ const nested = { art: new Date(0) };
523
+ assert.ok(!sameAs(nested, remember(nested)), 'nor anything holding one');
524
+ }
525
+
526
+ // Review findings 3 and 4, each repro by name.
527
+ function valuesThatCompute() {
528
+ // 3: a getter is never called to remember a value, and a value with one is
529
+ // never "the same", so it is read only by the signature, as it always was.
530
+ let reads = 0;
531
+ const live = { kind: 'box' };
532
+ Object.defineProperty(live, 'color', { enumerable: true, get: () => ['red', 'blue', 'green'][reads++ % 3] });
533
+ const memory = remember(live);
534
+ assert.equal(reads, 0, 'remembering does not call the getter');
535
+ assert.ok(!sameAs(live, memory));
536
+ assert.equal(reads, 0, 'nor does comparing');
537
+ const holder = { shape: live };
538
+ assert.ok(!sameAs(holder, remember(holder)), 'nor is anything holding it the same');
539
+ assert.equal(reads, 0);
540
+ const list = [1, 2];
541
+ Object.defineProperty(list, 0, { get: () => ++reads });
542
+ assert.ok(!sameAs(list, remember(list)), 'an array with a computed item');
543
+ assert.equal(reads, 0);
544
+
545
+ // 4: an array with a toJSON whose answer changes.
546
+ let answer = [1];
547
+ const array = [1];
548
+ array.toJSON = () => answer;
549
+ const arrayMemory = remember(array);
550
+ const before = JSON.stringify(array);
551
+ answer = [2];
552
+ assert.notEqual(JSON.stringify(array), before);
553
+ assert.ok(!sameAs(array, arrayMemory), 'an array with toJSON takes the string path');
554
+
555
+ // 4: a non-enumerable toJSON added to a remembered plain object.
556
+ const shape = { width: 1 };
557
+ const shapeMemory = remember(shape);
558
+ Object.defineProperty(shape, 'toJSON', { value: () => ({ width: 2 }), enumerable: false });
559
+ assert.equal(JSON.stringify(shape), '{"width":2}');
560
+ assert.ok(!sameAs(shape, shapeMemory), 'a toJSON added later, enumerable or not');
561
+ const inherited = { width: 1 };
562
+ const inheritedMemory = remember(inherited);
563
+ Object.setPrototypeOf(inherited, { toJSON: () => 3 });
564
+ assert.ok(!sameAs(inherited, inheritedMemory), 'or inherited');
565
+
566
+ // 4: an own field deleted and handed to a new prototype.
567
+ const body = { width: 1 };
568
+ const bodyMemory = remember(body);
569
+ delete body.width;
570
+ Object.setPrototypeOf(body, { width: 1 });
571
+ assert.equal(JSON.stringify(body), '{}');
572
+ assert.ok(!sameAs(body, bodyMemory), 'a field carried by a swapped prototype');
573
+ const carried = Object.create({ width: 1 });
574
+ assert.ok(!sameAs(carried, remember(carried)), 'or by the prototype it always had');
575
+ class Odd extends Array {}
576
+ const odd = Odd.from([1]);
577
+ assert.ok(!sameAs(odd, remember(odd)), 'an array of another class');
578
+
579
+ // Second review, 2: a toJSON that is itself a getter is not called, by
580
+ // remembering or by comparing, whether it was there from the start, came
581
+ // later, or is inherited.
582
+ let asked = 0;
583
+ const counting = { get: () => (asked += 1, () => ({ width: asked })), configurable: true };
584
+ const early = Object.defineProperty({ width: 1 }, 'toJSON', counting);
585
+ const earlyMemory = remember(early);
586
+ assert.ok(!sameAs(early, earlyMemory));
587
+ const late = { width: 1 };
588
+ const lateMemory = remember(late);
589
+ Object.defineProperty(late, 'toJSON', counting);
590
+ assert.ok(!sameAs(late, lateMemory), 'a toJSON getter added later');
591
+ const heir = Object.create(Object.defineProperty({}, 'toJSON', counting));
592
+ assert.ok(!sameAs(heir, remember(heir)));
593
+ const within = { art: early, list: [late] };
594
+ assert.ok(!sameAs(within, remember(within)));
595
+ assert.equal(asked, 0, 'no toJSON getter was called');
596
+
597
+ // Second review, 5: an array is remembered by index, as JSON reads it, not
598
+ // by its iterator.
599
+ const repeat = [1];
600
+ repeat[Symbol.iterator] = function* () {
601
+ yield 2;
602
+ };
603
+ const repeatMemory = remember(repeat);
604
+ assert.ok(sameAs(repeat, repeatMemory), 'unchanged, it is the same');
605
+ repeat[0] = 2;
606
+ assert.equal(JSON.stringify(repeat), '[2]');
607
+ assert.ok(!sameAs(repeat, repeatMemory), 'an item changed under a custom iterator');
608
+ const sparse = [1, , 3]; // eslint-disable-line no-sparse-arrays
609
+ const sparseMemory = remember(sparse);
610
+ assert.ok(sameAs(sparse, sparseMemory));
611
+ sparse[1] = null;
612
+ assert.ok(!sameAs(sparse, sparseMemory), 'a hole filled');
613
+ }
614
+
615
+ function readsAreRecorded() {
616
+ const sprites = { 'a.sprite': { id: 1 }, 'b.sprite': { id: 2 } };
617
+ const reads = [];
618
+ const table = recordReads(sprites, reads);
619
+ assert.equal(table['a.sprite'], sprites['a.sprite']);
620
+ assert.equal(table?.['missing.sprite'], undefined);
621
+ assert.deepEqual(reads, ['a.sprite', sprites['a.sprite'], 'missing.sprite', undefined]);
622
+ const none = [];
623
+ assert.equal(recordReads(undefined, none)?.['a.sprite'], undefined, 'no table reads as an empty one');
624
+ assert.deepEqual(none, ['a.sprite', undefined]);
625
+ }
626
+
627
+ // A plain value deeper than a call stack allows (a fourth review's case): it
628
+ // is not walked to the bottom and nothing is thrown; it is "never the same",
629
+ // so its signature is built every frame, as it always was.
630
+ function deepValues() {
631
+ const deep = { kind: 'box' };
632
+ let at = deep;
633
+ for (let i = 0; i < 3000; i++) {
634
+ at.inner = {};
635
+ at = at.inner;
636
+ }
637
+ const memory = remember(deep);
638
+ assert.ok(!sameAs(deep, memory), 'too deep to vouch for');
639
+ const shallow = { a: { b: { c: [1, { d: 2 }] } } };
640
+ assert.ok(sameAs(shallow, remember(shallow)), 'a few levels is fine');
641
+ const round = { kind: 'box' };
642
+ round.self = round;
643
+ assert.ok(!sameAs(round, remember(round)), 'a value that holds itself');
644
+ }
645
+
646
+ const trees = runTrees();
647
+ assert.ok(trees.skipped > 500, `still frames are skipped (${trees.skipped})`);
648
+ stillTreeIsSkipped();
649
+ staleMatricesAreSeen();
650
+ offIsAGroup();
651
+ recordHoldsNumbersOnly();
652
+ isAGroup();
653
+ const values = runValues();
654
+ valueEdges();
655
+ valuesThatCompute();
656
+ deepValues();
657
+ const passes = await (await import('./test-static-passes.mjs')).run();
658
+ const physics = await (await import('./test-static-physics.mjs')).run();
659
+ const shadows = await (await import('./test-near-shadows.mjs')).run();
660
+ const camera = await (await import('./test-camera-follow.mjs')).run();
661
+ const hover = await import('./test-steady-hover.mjs');
662
+ const steady = hover.summary(await hover.run());
663
+ const orbitTest = await import('./test-camera-orbit.mjs');
664
+ const orbit = orbitTest.summary(await orbitTest.run());
665
+ const dropped = await (await import('./test-drop-empty-parts.mjs')).run();
666
+ readsAreRecorded();
667
+ console.log(`static actors: ${trees.frames} tree frames equal a plain Group's (${trees.skipped} skipped), ${values.yes + values.no} value checks, ${passes} pass scenarios end as without the key, ${physics} physics scenarios keep nothing past their world, ${shadows} near-shadow scenarios leave the sun as it was, ${camera.checks} follow-camera checks, ${steady}, ${orbit}, ${dropped}`);