@threenative/core 0.3.6 → 0.3.9

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 (137) hide show
  1. package/README.md +3 -5
  2. package/capabilities.json +739 -50
  3. package/dist/{assets-CqvE429w.d.ts → assets-YUbXa3-Y.d.ts} +101 -2
  4. package/dist/{canvas-layer-C1-5CviZ.d.ts → canvas-layer-vCtanIeB.d.ts} +1 -1
  5. package/dist/{game-Jz4Fdoeb.d.ts → game-cb99J-YE.d.ts} +100 -31
  6. package/dist/hot.d.ts +4 -4
  7. package/dist/hot.js +23 -5
  8. package/dist/index.d.ts +1742 -29
  9. package/dist/index.js +22443 -12423
  10. package/dist/{model-lod-BDAUYgsS.d.ts → model-lod-CTpZ6imz.d.ts} +1 -1
  11. package/dist/net.js +39 -12
  12. package/dist/playtest.d.ts +4 -4
  13. package/dist/playtest.js +48 -9
  14. package/dist/react-css.js +23 -0
  15. package/dist/react.d.ts +2 -2
  16. package/dist/{renderer-9yEo9hPa.d.ts → renderer-rZm0hVqq.d.ts} +178 -5
  17. package/dist/ui-layer.d.ts +11 -2
  18. package/dist/ui-layer.js +76 -4
  19. package/dist/worker.d.ts +36 -0
  20. package/dist/worker.js +1088 -0
  21. package/dist/world.d.ts +11 -3
  22. package/dist/world.js +1117 -197
  23. package/mcp/animation-server.mjs +265 -0
  24. package/mcp/animation.mjs +22 -0
  25. package/mcp/call.mjs +105 -0
  26. package/mcp/devtools.mjs +5 -0
  27. package/mcp/engine-server.mjs +713 -37
  28. package/mcp/launch.mjs +3 -2
  29. package/mcp/servers.d.mts +2 -0
  30. package/mcp/servers.mjs +33 -8
  31. package/package.json +12 -8
  32. package/patches/three@0.185.1-prd269-upgrade.patch +308 -0
  33. package/patches/three@0.185.1.patch +481 -272
  34. package/src/animation-packet-state.ts +88 -0
  35. package/src/animation-pose-packet.ts +537 -0
  36. package/src/animation.ts +779 -31
  37. package/src/asset-cache.ts +719 -0
  38. package/src/assets.ts +521 -152
  39. package/src/audio.ts +29 -3
  40. package/src/auto-batch.ts +792 -0
  41. package/src/config.ts +2 -0
  42. package/src/frame-budget.ts +268 -2
  43. package/src/game.ts +525 -105
  44. package/src/grounding.ts +7 -6
  45. package/src/hot.ts +19 -5
  46. package/src/index.ts +381 -6
  47. package/src/input.ts +21 -2
  48. package/src/interpolation.ts +19 -1
  49. package/src/launch-diagnostics.ts +7 -2
  50. package/src/look/ao-multibounce.ts +29 -0
  51. package/src/look/ao-reach.ts +39 -0
  52. package/src/look/auto-exposure.ts +264 -0
  53. package/src/look/default-tone-mapping.ts +44 -0
  54. package/src/look/exposure-graph.ts +208 -0
  55. package/src/look/exposure-readback.ts +97 -0
  56. package/src/look/exposure-settings.ts +132 -0
  57. package/src/look/filmic-tone-mapping.ts +852 -0
  58. package/src/look/gi-registry.ts +55 -0
  59. package/src/look/local-exposure.ts +507 -0
  60. package/src/look/look-diagnostics.ts +24 -0
  61. package/src/look/motion-blur.ts +42 -0
  62. package/src/look/quality.ts +309 -0
  63. package/src/look/reflection-trace.ts +344 -0
  64. package/src/look/unreal-bloom.ts +295 -0
  65. package/src/look/vignette.ts +14 -0
  66. package/src/look/world-environment.ts +2033 -0
  67. package/src/loop.ts +25 -1
  68. package/src/merge-parts.ts +25 -10
  69. package/src/model-lod.ts +14 -0
  70. package/src/net-session.ts +58 -14
  71. package/src/ocean/spectral.ts +41 -7
  72. package/src/picking.ts +72 -5
  73. package/src/platform.ts +29 -1
  74. package/src/playtest.ts +54 -8
  75. package/src/profiling/FrameCounters.ts +166 -5
  76. package/src/profiling/FrameStages.ts +289 -0
  77. package/src/profiling/Spans.ts +39 -25
  78. package/src/profiling/debug-telemetry.ts +312 -0
  79. package/src/profiling/scene-warning.ts +42 -6
  80. package/src/projection-apply.ts +11 -3
  81. package/src/projection-content.ts +189 -0
  82. package/src/projection-marker.ts +6 -2
  83. package/src/projection-plan.ts +279 -28
  84. package/src/projection-skinned.ts +620 -5
  85. package/src/projection-stability.ts +16 -0
  86. package/src/projection-uniform.ts +5 -1
  87. package/src/quiet-markers.ts +56 -0
  88. package/src/render/budget-ladder.ts +256 -0
  89. package/src/render/chain.ts +89 -7
  90. package/src/render/exposure-units.ts +59 -0
  91. package/src/render/frame-time-budget.ts +162 -0
  92. package/src/render/gi-budget.ts +231 -0
  93. package/src/render/gi-visualize.ts +49 -0
  94. package/src/render/material-key.ts +1 -0
  95. package/src/render/probe-volume.ts +196 -36
  96. package/src/render/rough-diffuse.ts +177 -0
  97. package/src/render/scene-trace.ts +532 -0
  98. package/src/render/shadow-filter-budget.ts +237 -0
  99. package/src/render/sky-capture.ts +194 -0
  100. package/src/render/soft-shadow.ts +607 -0
  101. package/src/render/surface-cache.ts +418 -0
  102. package/src/render/traced-reflections.ts +408 -0
  103. package/src/render/two-sided-foliage.ts +120 -0
  104. package/src/render/virtual-shadow-pages.ts +112 -12
  105. package/src/render/virtual-shadow.ts +386 -38
  106. package/src/render-camera-cull.ts +536 -31
  107. package/src/render-pass-budget.ts +140 -22
  108. package/src/renderProjection.ts +65 -9
  109. package/src/renderer-config.ts +3 -2
  110. package/src/renderer.ts +289 -14
  111. package/src/resolution-scaler.ts +65 -7
  112. package/src/skeletal-mesh.ts +4 -0
  113. package/src/snow-field.ts +46 -0
  114. package/src/softbody.ts +6 -5
  115. package/src/startup-offscreen-bytes.ts +168 -0
  116. package/src/startup-readiness.ts +137 -2
  117. package/src/ui-bridge.ts +38 -0
  118. package/src/ui-hit-regions.ts +6 -2
  119. package/src/ui-layer.ts +1 -0
  120. package/src/ui-state.ts +32 -3
  121. package/src/version.ts +1 -1
  122. package/src/viewport.ts +8 -5
  123. package/src/warmup.ts +76 -10
  124. package/src/worker-audio.ts +579 -0
  125. package/src/worker.ts +842 -0
  126. package/src/world-cells.ts +4 -1
  127. package/gpl/LICENSE.GPL +0 -117
  128. package/gpl/convert.py +0 -192
  129. package/gpl/fixtures/make_world_fixture.py +0 -184
  130. package/gpl/recipes/_common.py +0 -180
  131. package/gpl/recipes/bake_ao.py +0 -111
  132. package/gpl/recipes/decimate.py +0 -70
  133. package/gpl/recipes/export_world.py +0 -699
  134. package/gpl/recipes/retarget.py +0 -131
  135. package/gpl/recipes/unwrap.py +0 -71
  136. package/mcp/blender-server.mjs +0 -689
  137. package/mcp/blender.mjs +0 -26
@@ -0,0 +1,189 @@
1
+ import type { BufferAttribute, BufferGeometry, InterleavedBufferAttribute } from "three";
2
+
3
+ /**
4
+ * Content identity for the render projection's instanced lanes.
5
+ *
6
+ * An agent-written game builds `new Mesh(new CylinderGeometry(...), material)` for every copy, so
7
+ * no two copies share a geometry object and a lane keyed on geometry identity batches nothing. The
8
+ * lanes key on a content class instead: every geometry whose attribute layout and bytes are equal
9
+ * shares one class, and the class's `canonical` geometry is what the instanced draw references for
10
+ * all its members. A class is decided once per geometry and kept while the geometry's attributes and
11
+ * versions hold; a geometry whose data moves after that is game-owned live data and leaves for a class
12
+ * of its own, never hashed again, so a streaming geometry costs a version check and nothing more.
13
+ */
14
+
15
+ /** One set of geometries with byte-identical vertex data. */
16
+ export interface IGeometryContentClass {
17
+ /** The member the batch draws for every member. Re-chosen when it leaves the scan or its data moves. */
18
+ canonical: BufferGeometry;
19
+ /** Attribute names, array types, item sizes and lengths, and the index: "" for a class of one. */
20
+ readonly layout: string;
21
+ /** The content hash, computed only once a second geometry of the same layout needs comparing. */
22
+ hash: number | undefined;
23
+ /** The scan that last saw a member, the first member it saw, and whether `canonical` was among them. */
24
+ scan: number;
25
+ first: BufferGeometry | undefined;
26
+ canonicalSeen: boolean;
27
+ }
28
+
29
+ /** A geometry's class, with the attribute identities and version sum that keep it valid. */
30
+ export interface IGeometryContentEntry {
31
+ /** Unset only between a first sighting and the end of the scan that classifies it. */
32
+ cls: IGeometryContentClass | undefined;
33
+ /** The attributes in iteration order, then the index: a swapped attribute moves no version. */
34
+ readonly parts: unknown[];
35
+ sum: number;
36
+ scan: number;
37
+ /** Its data moved after it was classed: a class of its own from then on. */
38
+ streamed: boolean;
39
+ }
40
+
41
+ function versionOf(attribute: BufferAttribute | InterleavedBufferAttribute): number {
42
+ if ("isInterleavedBufferAttribute" in attribute) return attribute.data.version;
43
+ return attribute.version;
44
+ }
45
+
46
+ /** Records the attribute identities and version sum the entry is valid for. */
47
+ export function recordContentParts(entry: IGeometryContentEntry, geometry: BufferGeometry): void {
48
+ let count = 0;
49
+ let sum = 0;
50
+ for (const name in geometry.attributes) {
51
+ if (!Object.hasOwn(geometry.attributes, name)) continue;
52
+ const attribute = geometry.attributes[name] as BufferAttribute;
53
+ entry.parts[count] = attribute;
54
+ count += 1;
55
+ sum += versionOf(attribute);
56
+ }
57
+ const index = geometry.getIndex();
58
+ entry.parts[count] = index;
59
+ entry.parts.length = count + 1;
60
+ entry.sum = index === null ? sum : sum + versionOf(index);
61
+ }
62
+
63
+ /** Whether the geometry still holds the attributes, index and versions the entry recorded. */
64
+ export function contentPartsUnchanged(
65
+ entry: IGeometryContentEntry,
66
+ geometry: BufferGeometry,
67
+ ): boolean {
68
+ const parts = entry.parts;
69
+ let count = 0;
70
+ let sum = 0;
71
+ for (const name in geometry.attributes) {
72
+ if (!Object.hasOwn(geometry.attributes, name)) continue;
73
+ const attribute = geometry.attributes[name] as BufferAttribute;
74
+ if (parts[count] !== attribute) return false;
75
+ count += 1;
76
+ sum += versionOf(attribute);
77
+ }
78
+ const index = geometry.getIndex();
79
+ if (parts[count] !== index || parts.length !== count + 1) return false;
80
+ return (index === null ? sum : sum + versionOf(index)) === entry.sum;
81
+ }
82
+
83
+ /**
84
+ * Whether content identity applies at all. An instanced geometry's draw count and an interleaved
85
+ * buffer's stride are not in the bytes compared, so each keeps a class of its own.
86
+ */
87
+ export function contentMergeable(geometry: BufferGeometry): boolean {
88
+ if ((geometry as { isInstancedBufferGeometry?: boolean }).isInstancedBufferGeometry === true)
89
+ return false;
90
+ for (const name in geometry.attributes) {
91
+ if (!Object.hasOwn(geometry.attributes, name)) continue;
92
+ if ("isInterleavedBufferAttribute" in (geometry.attributes[name] as object)) return false;
93
+ }
94
+ return true;
95
+ }
96
+
97
+ function arrayOf(attribute: BufferAttribute): ArrayBufferView & { length: number } {
98
+ return attribute.array as ArrayBufferView & { length: number };
99
+ }
100
+
101
+ /** Everything but the bytes: two geometries with different layouts can never share a class. */
102
+ export function contentLayout(geometry: BufferGeometry): string {
103
+ const index = geometry.getIndex();
104
+ let layout =
105
+ index === null ? "n" : `i${arrayOf(index).constructor.name}:${arrayOf(index).length}`;
106
+ const names = Object.keys(geometry.attributes).sort();
107
+ for (let at = 0; at < names.length; at += 1) {
108
+ const name = names[at] as string;
109
+ const attribute = geometry.attributes[name] as BufferAttribute;
110
+ const array = arrayOf(attribute);
111
+ layout += ` ${name}:${attribute.itemSize}:${attribute.normalized ? 1 : 0}:${array.constructor.name}:${array.length}`;
112
+ }
113
+ return layout;
114
+ }
115
+
116
+ function words(view: ArrayBufferView): Int32Array | undefined {
117
+ return view.byteOffset % 4 === 0
118
+ ? new Int32Array(view.buffer, view.byteOffset, view.byteLength >> 2)
119
+ : undefined;
120
+ }
121
+
122
+ function hashView(seed: number, view: ArrayBufferView): number {
123
+ let hash = seed;
124
+ const packed = words(view);
125
+ let tail = 0;
126
+ if (packed !== undefined) {
127
+ for (let at = 0; at < packed.length; at += 1)
128
+ hash = Math.imul(hash ^ (packed[at] as number), 0x01000193);
129
+ tail = packed.length * 4;
130
+ }
131
+ const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
132
+ for (let at = tail; at < bytes.length; at += 1)
133
+ hash = Math.imul(hash ^ (bytes[at] as number), 0x01000193);
134
+ return hash;
135
+ }
136
+
137
+ /** FNV-1a over the index and every attribute's bytes, in name order. */
138
+ export function contentHash(geometry: BufferGeometry): number {
139
+ let hash = 0x811c9dc5;
140
+ const index = geometry.getIndex();
141
+ if (index !== null) hash = hashView(hash, arrayOf(index));
142
+ const names = Object.keys(geometry.attributes).sort();
143
+ for (let at = 0; at < names.length; at += 1)
144
+ hash = hashView(hash, arrayOf(geometry.attributes[names[at] as string] as BufferAttribute));
145
+ return hash >>> 0;
146
+ }
147
+
148
+ function sameView(a: ArrayBufferView, b: ArrayBufferView): boolean {
149
+ if (a.byteLength !== b.byteLength) return false;
150
+ const wordsA = words(a);
151
+ const wordsB = words(b);
152
+ let tail = 0;
153
+ if (wordsA !== undefined && wordsB !== undefined) {
154
+ for (let at = 0; at < wordsA.length; at += 1) if (wordsA[at] !== wordsB[at]) return false;
155
+ tail = wordsA.length * 4;
156
+ }
157
+ const bytesA = new Uint8Array(a.buffer, a.byteOffset, a.byteLength);
158
+ const bytesB = new Uint8Array(b.buffer, b.byteOffset, b.byteLength);
159
+ for (let at = tail; at < bytesA.length; at += 1) if (bytesA[at] !== bytesB[at]) return false;
160
+ return true;
161
+ }
162
+
163
+ /** The full byte compare behind an equal hash, for two geometries of one layout: no false merge. */
164
+ export function sameContent(a: BufferGeometry, b: BufferGeometry): boolean {
165
+ const indexA = a.getIndex();
166
+ const indexB = b.getIndex();
167
+ if ((indexA === null) !== (indexB === null)) return false;
168
+ if (indexA !== null && !sameView(arrayOf(indexA), arrayOf(indexB as BufferAttribute)))
169
+ return false;
170
+ for (const name in a.attributes) {
171
+ if (!Object.hasOwn(a.attributes, name)) continue;
172
+ const other = b.attributes[name] as BufferAttribute | undefined;
173
+ if (other === undefined) return false;
174
+ if (!sameView(arrayOf(a.attributes[name] as BufferAttribute), arrayOf(other))) return false;
175
+ }
176
+ return true;
177
+ }
178
+
179
+ /** A class of one: a geometry that content identity does not apply to, or whose data moved. */
180
+ export function ownContentClass(geometry: BufferGeometry): IGeometryContentClass {
181
+ return {
182
+ canonical: geometry,
183
+ layout: "",
184
+ hash: undefined,
185
+ scan: 0,
186
+ first: undefined,
187
+ canonicalSeen: false,
188
+ };
189
+ }
@@ -1,6 +1,10 @@
1
1
  import type { IMatrixWorldReport } from "./matrix-world.js";
2
2
  import type { IRenderCameraCullReport } from "./render-camera-cull.js";
3
- import type { IRenderProjectionReport, ProjectionExactReason } from "./renderProjection.js";
3
+ import type {
4
+ IRenderProjectionReport,
5
+ ProjectionExactReason,
6
+ ProjectionWindowReport,
7
+ } from "./renderProjection.js";
4
8
 
5
9
  /**
6
10
  * The per-window projection line.
@@ -99,7 +103,7 @@ export function rankExactReasons(
99
103
  * to do".
100
104
  */
101
105
  export function formatProjectionWindow(
102
- report: IRenderProjectionReport,
106
+ report: ProjectionWindowReport,
103
107
  window: number,
104
108
  drawsActual: number | undefined,
105
109
  cull?: IRenderCameraCullReport,
@@ -10,7 +10,19 @@ import type {
10
10
  SkinnedMesh,
11
11
  } from "three";
12
12
 
13
+ import { isAutoBatchSource } from "./auto-batch.js";
13
14
  import { isEngineRenderHook } from "./engine-render-hook.js";
15
+ import {
16
+ type IGeometryContentClass,
17
+ type IGeometryContentEntry,
18
+ contentHash,
19
+ contentLayout,
20
+ contentMergeable,
21
+ contentPartsUnchanged,
22
+ ownContentClass,
23
+ recordContentParts,
24
+ sameContent,
25
+ } from "./projection-content.js";
14
26
  import { skinnedMaterialBlocked } from "./projection-skinned.js";
15
27
  import { uniformSignatureOf } from "./projection-uniform.js";
16
28
  import type { ProjectionExactReason, ProjectionReasonCode } from "./renderProjection.js";
@@ -298,10 +310,15 @@ class ProjectionSeen implements IProjectionSeenWorkspace {
298
310
  }
299
311
 
300
312
  /**
301
- * A reusable identity group for one (geometry, material, flags) combination.
313
+ * A reusable identity group for one (geometry content, material, flags) combination.
314
+ *
315
+ * `content` is the key: a rig's own geometry, or the content class of a rigid mesh's geometry, so
316
+ * copies that each built the same shape share a group. `geometry` is what the batch draws for every
317
+ * member, the class's canonical one, set again on each scan that activates the group.
302
318
  */
303
319
  export interface IProjectionBatchGroup {
304
- readonly geometry: BufferGeometry;
320
+ geometry: BufferGeometry;
321
+ readonly content: object;
305
322
  readonly material: Material;
306
323
  readonly castShadow: boolean;
307
324
  readonly receiveShadow: boolean;
@@ -398,19 +415,24 @@ export interface IProjectionScanWorkspace {
398
415
  activeGroupCount: number;
399
416
  readonly walkStack: Array<Object3D | undefined>;
400
417
  walkStackCount: number;
401
- readonly groupsByGeometry: WeakMap<
402
- BufferGeometry,
403
- WeakMap<Material, Map<number, IProjectionBatchGroup>>
404
- >;
418
+ /** Rigid groups by geometry content class, then material, then flags. */
419
+ readonly groupsByContent: WeakMap<object, WeakMap<Material, Map<number, IProjectionBatchGroup>>>;
405
420
  /**
406
- * Uniform groups, by geometry, then by the material signature, then by the batching flags — a
407
- * signature is a value, so the geometry key has to be the weak one for the index not to outlive
408
- * the geometry it describes.
421
+ * Uniform groups, by geometry content class, then by the material signature, then by the batching
422
+ * flags — a signature is a value, so the class key has to be the weak one for the index not to
423
+ * outlive the geometries it describes.
409
424
  */
410
- readonly uniformGroups: WeakMap<
411
- BufferGeometry,
412
- Map<string, Map<number, IProjectionUniformGroup>>
413
- >;
425
+ readonly uniformGroups: WeakMap<object, Map<string, Map<number, IProjectionUniformGroup>>>;
426
+ /** Each geometry's content class and the attribute versions it holds for (projection-content.ts). */
427
+ readonly geometryContent: WeakMap<BufferGeometry, IGeometryContentEntry>;
428
+ /** The content entry of each eligible mesh, by its index in `eligible`. */
429
+ readonly eligibleContent: Array<IGeometryContentEntry | undefined>;
430
+ /** Geometries first seen this scan, classified together once the walk has seen every class. */
431
+ readonly pendingContent: Array<BufferGeometry | undefined>;
432
+ pendingContentCount: number;
433
+ /** Content classes with a member this scan, so each re-chooses its canonical geometry once. */
434
+ readonly touchedClasses: Array<IGeometryContentClass | undefined>;
435
+ touchedClassCount: number;
414
436
  readonly activeUniformGroups: Array<IProjectionUniformGroup | undefined>;
415
437
  activeUniformGroupCount: number;
416
438
  /** The uniform group each mesh was filed under, so nothing files it a second time this scan. */
@@ -433,11 +455,25 @@ export interface IProjectionScanWorkspace {
433
455
  scanNumber: number;
434
456
  }
435
457
 
458
+ /**
459
+ * Why a `notWorthwhile` frame had too many meshes drawing alone. `uniqueGeometry`: copies whose
460
+ * geometry data differs (or that are one of a kind); `uniqueMaterial`: copies that share a shape but
461
+ * not a material beyond its colour, or not their shadow and layer flags.
462
+ */
463
+ export type ProjectionDeclineCauseCode = "uniqueGeometry" | "uniqueMaterial";
464
+
465
+ export interface IProjectionDeclineCount {
466
+ readonly code: ProjectionDeclineCauseCode;
467
+ /** Meshes left drawing alone for that cause. */
468
+ readonly meshes: number;
469
+ }
470
+
436
471
  /** Gives the frame back to the authored scene, naming why. */
437
472
  export interface IProjectionDeclinePlan {
438
473
  readonly action: "decline";
439
474
  readonly reasonCode: ProjectionReasonCode;
440
475
  readonly reason: string;
476
+ readonly cause?: IProjectionDeclineCount;
441
477
  }
442
478
 
443
479
  /** Everything the apply seam needs to build and maintain this frame's mirror. */
@@ -507,8 +543,14 @@ export function createProjectionScanWorkspace(): IProjectionScanWorkspace {
507
543
  activeGroupCount: 0,
508
544
  walkStack: [],
509
545
  walkStackCount: 0,
510
- groupsByGeometry: new WeakMap(),
546
+ groupsByContent: new WeakMap(),
511
547
  uniformGroups: new WeakMap(),
548
+ geometryContent: new WeakMap(),
549
+ eligibleContent: [],
550
+ pendingContent: [],
551
+ pendingContentCount: 0,
552
+ touchedClasses: [],
553
+ touchedClassCount: 0,
512
554
  activeUniformGroups: [],
513
555
  activeUniformGroupCount: 0,
514
556
  uniformOf: new WeakMap(),
@@ -570,6 +612,15 @@ function releaseSkinnedScan(workspace: IProjectionScanWorkspace): void {
570
612
  workspace.skinnedGroupCount = 0;
571
613
  }
572
614
 
615
+ /** The content lane's share: a class keeps no first member of a scan that ended. */
616
+ function releaseContentScan(workspace: IProjectionScanWorkspace): void {
617
+ for (let index = 0; index < workspace.touchedClassCount; index += 1) {
618
+ (workspace.touchedClasses[index] as IGeometryContentClass).first = undefined;
619
+ workspace.touchedClasses[index] = undefined;
620
+ }
621
+ workspace.touchedClassCount = 0;
622
+ }
623
+
573
624
  export function releaseProjectionScanWorkspace(workspace: IProjectionScanWorkspace): void {
574
625
  for (let index = 0; index < workspace.exactEntryPool.length; index += 1) {
575
626
  const entry = workspace.exactEntryPool[index] as IProjectionExactEntry;
@@ -600,7 +651,9 @@ export function releaseProjectionScanWorkspace(workspace: IProjectionScanWorkspa
600
651
  }
601
652
  for (let index = 0; index < workspace.eligibleCount; index += 1) {
602
653
  workspace.eligible[index] = undefined;
654
+ workspace.eligibleContent[index] = undefined;
603
655
  }
656
+ releaseContentScan(workspace);
604
657
  releaseSkinnedScan(workspace);
605
658
  for (let index = 0; index < workspace.exactLaneCount; index += 1) {
606
659
  const entry = workspace.exactLane[index] as IProjectionExactEntry;
@@ -663,11 +716,12 @@ function batchFlagsOf(mesh: Mesh): number {
663
716
  function addToBatchGroup(
664
717
  workspace: IProjectionScanWorkspace,
665
718
  mesh: Mesh,
719
+ content: IGeometryContentClass,
666
720
  scanNumber: number,
667
721
  ): void {
668
- const byFlags = flagGroupsOf(workspace.groupsByGeometry, mesh);
722
+ const byFlags = flagGroupsOf(workspace.groupsByContent, content, mesh);
669
723
  const flags = batchFlagsOf(mesh);
670
- const group = activeGroupOf(byFlags, flags, mesh, scanNumber);
724
+ const group = activeGroupOf(byFlags, flags, mesh, content, content.canonical, scanNumber);
671
725
  if (group.memberCount === 0) {
672
726
  workspace.activeGroups[workspace.activeGroupCount] = group;
673
727
  workspace.activeGroupCount += 1;
@@ -685,10 +739,10 @@ function addToSkinnedGroup(
685
739
  mesh: SkinnedMesh,
686
740
  scanNumber: number,
687
741
  ): void {
688
- const byFlags = flagGroupsOf(workspace.skinnedGroupsByGeometry, mesh);
742
+ const byFlags = flagGroupsOf(workspace.skinnedGroupsByGeometry, mesh.geometry, mesh);
689
743
  // Bone counts stay far below 2^16, so the composite key stays an exact integer.
690
744
  const key = batchFlagsOf(mesh) * 65536 + mesh.skeleton.bones.length;
691
- const group = activeGroupOf(byFlags, key, mesh, scanNumber);
745
+ const group = activeGroupOf(byFlags, key, mesh, mesh.geometry, mesh.geometry, scanNumber);
692
746
  if (group.memberCount === 0) {
693
747
  workspace.activeSkinnedGroups[workspace.activeSkinnedGroupCount] = group;
694
748
  workspace.activeSkinnedGroupCount += 1;
@@ -698,15 +752,15 @@ function addToSkinnedGroup(
698
752
  }
699
753
 
700
754
  function flagGroupsOf(
701
- index: WeakMap<BufferGeometry, WeakMap<Material, Map<number, IProjectionBatchGroup>>>,
755
+ index: WeakMap<object, WeakMap<Material, Map<number, IProjectionBatchGroup>>>,
756
+ content: object,
702
757
  mesh: Mesh,
703
758
  ): Map<number, IProjectionBatchGroup> {
704
- const geometry = mesh.geometry;
705
759
  const material = mesh.material as Material;
706
- let byMaterial = index.get(geometry);
760
+ let byMaterial = index.get(content);
707
761
  if (byMaterial === undefined) {
708
762
  byMaterial = new WeakMap();
709
- index.set(geometry, byMaterial);
763
+ index.set(content, byMaterial);
710
764
  }
711
765
  let byFlags = byMaterial.get(material);
712
766
  if (byFlags === undefined) {
@@ -721,14 +775,16 @@ function activeGroupOf(
721
775
  byFlags: Map<number, IProjectionBatchGroup>,
722
776
  key: number,
723
777
  mesh: Mesh,
778
+ content: object,
779
+ geometry: BufferGeometry,
724
780
  scanNumber: number,
725
781
  ): IProjectionBatchGroup {
726
- const geometry = mesh.geometry;
727
782
  const material = mesh.material as Material;
728
783
  let group = byFlags.get(key);
729
784
  if (group === undefined) {
730
785
  group = {
731
786
  geometry,
787
+ content,
732
788
  material,
733
789
  castShadow: mesh.castShadow,
734
790
  receiveShadow: mesh.receiveShadow,
@@ -743,6 +799,7 @@ function activeGroupOf(
743
799
  if (group.activeScan !== scanNumber) {
744
800
  group.activeScan = scanNumber;
745
801
  group.memberCount = 0;
802
+ group.geometry = geometry;
746
803
  }
747
804
  return group;
748
805
  }
@@ -810,17 +867,19 @@ export function geometryVersionSum(geometry: BufferGeometry): number {
810
867
  function addToUniformGroup(
811
868
  workspace: IProjectionScanWorkspace,
812
869
  mesh: Mesh,
870
+ owner: IProjectionBatchGroup,
813
871
  scanNumber: number,
814
872
  ): void {
815
- const geometry = mesh.geometry;
873
+ const content = owner.content;
874
+ const geometry = owner.geometry;
816
875
  const material = mesh.material as Material;
817
876
  const signature = uniformSignatureOf(material);
818
877
  if (signature === undefined) return;
819
878
  const flags = batchFlagsOf(mesh);
820
- let bySignature = workspace.uniformGroups.get(geometry);
879
+ let bySignature = workspace.uniformGroups.get(content);
821
880
  if (bySignature === undefined) {
822
881
  bySignature = new Map();
823
- workspace.uniformGroups.set(geometry, bySignature);
882
+ workspace.uniformGroups.set(content, bySignature);
824
883
  }
825
884
  let byFlags = bySignature.get(signature);
826
885
  if (byFlags === undefined) {
@@ -831,6 +890,7 @@ function addToUniformGroup(
831
890
  if (group === undefined) {
832
891
  group = {
833
892
  geometry,
893
+ content,
834
894
  material,
835
895
  castShadow: mesh.castShadow,
836
896
  receiveShadow: mesh.receiveShadow,
@@ -846,6 +906,7 @@ function addToUniformGroup(
846
906
  if (group.activeScan !== scanNumber) {
847
907
  group.activeScan = scanNumber;
848
908
  group.memberCount = 0;
909
+ group.geometry = geometry;
849
910
  workspace.activeUniformGroups[workspace.activeUniformGroupCount] = group;
850
911
  workspace.activeUniformGroupCount += 1;
851
912
  }
@@ -1002,6 +1063,9 @@ function visitProjectionObject(
1002
1063
  addExactEntry(workspace, object, "lod");
1003
1064
  return;
1004
1065
  }
1066
+ // Drawn through its merged mesh, which is walked in its place: a slot here would be a draw of
1067
+ // nothing.
1068
+ if (isAutoBatchSource(object)) return;
1005
1069
  if (!isRenderable(object)) return;
1006
1070
  state.renderables += 1;
1007
1071
  workspace.seen.add(object);
@@ -1042,9 +1106,194 @@ function walkProjection(source: Scene, workspace: IProjectionScanWorkspace): IPr
1042
1106
  return state;
1043
1107
  }
1044
1108
 
1109
+ /** Counts a class as seen this scan, keeping its first member in case the canonical one is gone. */
1110
+ function touchContentClass(
1111
+ workspace: IProjectionScanWorkspace,
1112
+ content: IGeometryContentClass,
1113
+ geometry: BufferGeometry,
1114
+ scanNumber: number,
1115
+ ): void {
1116
+ if (content.scan !== scanNumber) {
1117
+ content.scan = scanNumber;
1118
+ content.first = geometry;
1119
+ content.canonicalSeen = false;
1120
+ workspace.touchedClasses[workspace.touchedClassCount] = content;
1121
+ workspace.touchedClassCount += 1;
1122
+ }
1123
+ if (content.canonical === geometry) content.canonicalSeen = true;
1124
+ }
1125
+
1126
+ /**
1127
+ * The geometry's content entry for this scan. A known geometry whose attributes and versions hold
1128
+ * keeps its class; one whose data moved leaves for a class of its own and is never hashed again. A
1129
+ * geometry seen for the first time waits for `classifyPendingContent`.
1130
+ */
1131
+ function contentEntryOf(
1132
+ workspace: IProjectionScanWorkspace,
1133
+ geometry: BufferGeometry,
1134
+ scanNumber: number,
1135
+ ): IGeometryContentEntry {
1136
+ let entry = workspace.geometryContent.get(geometry);
1137
+ if (entry !== undefined && entry.scan === scanNumber) return entry;
1138
+ if (entry === undefined) {
1139
+ entry = { cls: undefined, parts: [], sum: 0, scan: scanNumber, streamed: false };
1140
+ workspace.geometryContent.set(geometry, entry);
1141
+ recordContentParts(entry, geometry);
1142
+ if (contentMergeable(geometry)) {
1143
+ workspace.pendingContent[workspace.pendingContentCount] = geometry;
1144
+ workspace.pendingContentCount += 1;
1145
+ return entry;
1146
+ }
1147
+ entry.streamed = true;
1148
+ entry.cls = ownContentClass(geometry);
1149
+ } else {
1150
+ entry.scan = scanNumber;
1151
+ if (!contentPartsUnchanged(entry, geometry)) {
1152
+ recordContentParts(entry, geometry);
1153
+ if (!entry.streamed) {
1154
+ entry.streamed = true;
1155
+ entry.cls = ownContentClass(geometry);
1156
+ }
1157
+ }
1158
+ }
1159
+ touchContentClass(workspace, entry.cls as IGeometryContentClass, geometry, scanNumber);
1160
+ return entry;
1161
+ }
1162
+
1163
+ /**
1164
+ * Files each first-seen geometry under the class whose bytes it equals, or a new one. Candidates are
1165
+ * the classes seen this scan with the same layout; a hash is computed only when a layout repeats,
1166
+ * and an equal hash still needs the full byte compare.
1167
+ */
1168
+ function matchingContentClass(
1169
+ bucket: readonly IGeometryContentClass[],
1170
+ geometry: BufferGeometry,
1171
+ hash: number,
1172
+ ): IGeometryContentClass | undefined {
1173
+ for (let at = 0; at < bucket.length; at += 1) {
1174
+ const candidate = bucket[at] as IGeometryContentClass;
1175
+ // A member seen this scan, so its bytes are still the class's.
1176
+ const member = candidate.canonicalSeen
1177
+ ? candidate.canonical
1178
+ : (candidate.first as BufferGeometry);
1179
+ candidate.hash ??= contentHash(member);
1180
+ if (candidate.hash === hash && sameContent(member, geometry)) return candidate;
1181
+ }
1182
+ return undefined;
1183
+ }
1184
+
1185
+ /** This scan's comparable classes by layout. Allocated only on a scan that meets a new geometry. */
1186
+ function classesByLayout(
1187
+ workspace: IProjectionScanWorkspace,
1188
+ ): Map<string, IGeometryContentClass[]> {
1189
+ const byLayout = new Map<string, IGeometryContentClass[]>();
1190
+ for (let index = 0; index < workspace.touchedClassCount; index += 1) {
1191
+ const content = workspace.touchedClasses[index] as IGeometryContentClass;
1192
+ if (content.layout === "") continue;
1193
+ const bucket = byLayout.get(content.layout);
1194
+ if (bucket === undefined) byLayout.set(content.layout, [content]);
1195
+ else bucket.push(content);
1196
+ }
1197
+ return byLayout;
1198
+ }
1199
+
1200
+ function classifyPendingContent(workspace: IProjectionScanWorkspace, scanNumber: number): void {
1201
+ const byLayout = classesByLayout(workspace);
1202
+ for (let index = 0; index < workspace.pendingContentCount; index += 1) {
1203
+ const geometry = workspace.pendingContent[index] as BufferGeometry;
1204
+ workspace.pendingContent[index] = undefined;
1205
+ const layout = contentLayout(geometry);
1206
+ const bucket = byLayout.get(layout);
1207
+ const hash = bucket === undefined ? undefined : contentHash(geometry);
1208
+ let found =
1209
+ bucket === undefined ? undefined : matchingContentClass(bucket, geometry, hash as number);
1210
+ if (found === undefined) {
1211
+ found = {
1212
+ canonical: geometry,
1213
+ layout,
1214
+ hash,
1215
+ scan: 0,
1216
+ first: undefined,
1217
+ canonicalSeen: false,
1218
+ };
1219
+ if (bucket === undefined) byLayout.set(layout, [found]);
1220
+ else bucket.push(found);
1221
+ }
1222
+ (workspace.geometryContent.get(geometry) as IGeometryContentEntry).cls = found;
1223
+ touchContentClass(workspace, found, geometry, scanNumber);
1224
+ }
1225
+ workspace.pendingContentCount = 0;
1226
+ }
1227
+
1228
+ /**
1229
+ * Resolves every eligible mesh's geometry to its content class, then gives each class a canonical
1230
+ * geometry that is in this scan: the one it had while that one is still a member, else its first.
1231
+ * A run of meshes sharing one geometry resolves it once.
1232
+ */
1233
+ function resolveGeometryContent(workspace: IProjectionScanWorkspace, scanNumber: number): void {
1234
+ let previous: BufferGeometry | undefined;
1235
+ let entry: IGeometryContentEntry | undefined;
1236
+ for (let index = 0; index < workspace.eligibleCount; index += 1) {
1237
+ const geometry = (workspace.eligible[index] as Mesh).geometry;
1238
+ if (geometry !== previous) {
1239
+ previous = geometry;
1240
+ entry = contentEntryOf(workspace, geometry, scanNumber);
1241
+ }
1242
+ workspace.eligibleContent[index] = entry;
1243
+ }
1244
+ if (workspace.pendingContentCount > 0) classifyPendingContent(workspace, scanNumber);
1245
+ for (let index = 0; index < workspace.touchedClassCount; index += 1) {
1246
+ const content = workspace.touchedClasses[index] as IGeometryContentClass;
1247
+ if (!content.canonicalSeen) content.canonical = content.first as BufferGeometry;
1248
+ }
1249
+ }
1250
+
1251
+ /** A below-floor group's members no uniform group claimed. A packed material batch still pays a sub-draw each. */
1252
+ function aloneMembers(workspace: IProjectionScanWorkspace, group: IProjectionBatchGroup): number {
1253
+ let alone = 0;
1254
+ for (let member = 0; member < group.memberCount; member += 1)
1255
+ if (!uniformClaimed(workspace, group.members[member] as Mesh)) alone += 1;
1256
+ return alone;
1257
+ }
1258
+
1259
+ /**
1260
+ * Why a declined frame has meshes drawing alone: a mesh whose content class has too few meshes in
1261
+ * the whole scene is held back by its geometry, one whose class has enough by its material or flags.
1262
+ * The larger count names the cause. Only a decline pays for this.
1263
+ */
1264
+ function declineCause(workspace: IProjectionScanWorkspace): IProjectionDeclineCount | undefined {
1265
+ const sizes = new Map<IGeometryContentClass, number>();
1266
+ for (let index = 0; index < workspace.eligibleCount; index += 1) {
1267
+ const content = (workspace.eligibleContent[index] as IGeometryContentEntry)
1268
+ .cls as IGeometryContentClass;
1269
+ sizes.set(content, (sizes.get(content) ?? 0) + 1);
1270
+ }
1271
+ let geometry = 0;
1272
+ let material = 0;
1273
+ for (let index = 0; index < workspace.activeGroupCount; index += 1) {
1274
+ const group = workspace.activeGroups[index] as IProjectionBatchGroup;
1275
+ if (group.memberCount >= MIN_BATCH_MEMBERS) continue;
1276
+ const alone = aloneMembers(workspace, group);
1277
+ if ((sizes.get(group.content as IGeometryContentClass) ?? 0) >= MIN_BATCH_MEMBERS)
1278
+ material += alone;
1279
+ else geometry += alone;
1280
+ }
1281
+ if (geometry + material === 0) return undefined;
1282
+ return geometry >= material
1283
+ ? { code: "uniqueGeometry", meshes: geometry }
1284
+ : { code: "uniqueMaterial", meshes: material };
1285
+ }
1286
+
1045
1287
  function groupEligibleMeshes(workspace: IProjectionScanWorkspace, scanNumber: number): void {
1288
+ resolveGeometryContent(workspace, scanNumber);
1046
1289
  for (let index = 0; index < workspace.eligibleCount; index += 1) {
1047
- addToBatchGroup(workspace, workspace.eligible[index] as Mesh, scanNumber);
1290
+ const content = (workspace.eligibleContent[index] as IGeometryContentEntry).cls;
1291
+ addToBatchGroup(
1292
+ workspace,
1293
+ workspace.eligible[index] as Mesh,
1294
+ content as IGeometryContentClass,
1295
+ scanNumber,
1296
+ );
1048
1297
  }
1049
1298
  for (let index = 0; index < workspace.skinnedCount; index += 1) {
1050
1299
  addToSkinnedGroup(workspace, workspace.skinned[index] as SkinnedMesh, scanNumber);
@@ -1062,7 +1311,7 @@ function groupEligibleMeshes(workspace: IProjectionScanWorkspace, scanNumber: nu
1062
1311
  const group = workspace.activeGroups[index] as IProjectionBatchGroup;
1063
1312
  if (group.memberCount >= MIN_BATCH_MEMBERS) continue;
1064
1313
  for (let member = 0; member < group.memberCount; member += 1) {
1065
- addToUniformGroup(workspace, group.members[member] as Mesh, scanNumber);
1314
+ addToUniformGroup(workspace, group.members[member] as Mesh, group, scanNumber);
1066
1315
  }
1067
1316
  }
1068
1317
  for (let index = 0; index < workspace.activeGroupCount; index += 1) {
@@ -1219,6 +1468,7 @@ export function scanProjection(
1219
1468
  groupEligibleMeshes(workspace, workspace.scanNumber);
1220
1469
  const predictedDraws = predictDraws(workspace);
1221
1470
  if (predictedDraws > state.renderables * WORTHWHILE_DRAW_RATIO) {
1471
+ const cause = declineCause(workspace);
1222
1472
  return {
1223
1473
  exactLane: workspace.exactLane,
1224
1474
  exactLaneCount: workspace.exactLaneCount,
@@ -1226,6 +1476,7 @@ export function scanProjection(
1226
1476
  action: "decline",
1227
1477
  reasonCode: "notWorthwhile",
1228
1478
  reason: `projecting would draw ${predictedDraws} of ${state.renderables} candidates, which is not worth its own cost`,
1479
+ ...(cause === undefined ? {} : { cause }),
1229
1480
  },
1230
1481
  renderables: state.renderables,
1231
1482
  seen: workspace.seen,