@threenative/core 0.3.3 → 0.3.5

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 (182) hide show
  1. package/capabilities.json +2019 -59
  2. package/dist/{assets-CYKk2WTu.d.ts → assets-CqvE429w.d.ts} +45 -3
  3. package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
  4. package/dist/{canvas-layer-C1SnMoJ-.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
  5. package/dist/{game-D_6r-k4Y.d.ts → game-Bj8G1wmD.d.ts} +242 -17
  6. package/dist/hot.d.ts +5 -5
  7. package/dist/index.d.ts +1131 -105
  8. package/dist/index.js +15201 -4782
  9. package/dist/model-lod-BDAUYgsS.d.ts +197 -0
  10. package/dist/playtest.d.ts +6 -4
  11. package/dist/playtest.js +84 -11
  12. package/dist/react-css.d.ts +62 -0
  13. package/dist/react-css.js +591 -0
  14. package/dist/react.d.ts +2 -2
  15. package/dist/{renderer-Cy4qeBOA.d.ts → renderer-9yEo9hPa.d.ts} +676 -21
  16. package/dist/terrain-jobs-worker.d.ts +2 -0
  17. package/dist/terrain-jobs-worker.js +130 -0
  18. package/dist/ui-layer.d.ts +5 -3
  19. package/dist/ui-layer.js +59 -8
  20. package/dist/world.d.ts +1596 -17
  21. package/dist/world.js +17035 -521
  22. package/gpl/fixtures/make_world_fixture.py +184 -0
  23. package/gpl/recipes/_common.py +11 -0
  24. package/gpl/recipes/decimate.py +11 -5
  25. package/gpl/recipes/export_world.py +699 -0
  26. package/mcp/blender-server.mjs +61 -4
  27. package/mcp/blender.mjs +3 -4
  28. package/mcp/engine-server.mjs +55 -21
  29. package/mcp/servers.mjs +4 -4
  30. package/package.json +15 -9
  31. package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
  32. package/patches/three@0.185.1.patch +8246 -389
  33. package/scripts/apply-three-patch.mjs +123 -41
  34. package/src/animation-blend.ts +264 -0
  35. package/src/animation-composition.ts +362 -0
  36. package/src/animation-layers.ts +260 -0
  37. package/src/animation-root-motion.ts +283 -0
  38. package/src/animation.ts +896 -0
  39. package/src/assets.ts +1303 -0
  40. package/src/atmosphere/index.ts +335 -0
  41. package/src/atmosphere/luts.ts +298 -0
  42. package/src/atmosphere/params.ts +323 -0
  43. package/src/audio.ts +912 -0
  44. package/src/billboard.ts +124 -0
  45. package/src/bone-lengths.ts +157 -0
  46. package/src/camera-shake.ts +116 -0
  47. package/src/canvas-layer.ts +47 -0
  48. package/src/clip-audit.ts +401 -0
  49. package/src/clustered-batch.ts +492 -0
  50. package/src/clustered-mesh.ts +638 -0
  51. package/src/compute-driven.ts +176 -0
  52. package/src/compute-timing.ts +318 -0
  53. package/src/config.ts +593 -0
  54. package/src/debug.ts +82 -0
  55. package/src/engine-render-hook.ts +25 -0
  56. package/src/entities.ts +79 -0
  57. package/src/entity-snapshot.ts +53 -0
  58. package/src/flight.ts +683 -0
  59. package/src/fluid-field.ts +748 -0
  60. package/src/fluid-particles.ts +1253 -0
  61. package/src/frame-budget.ts +1368 -0
  62. package/src/game.ts +2390 -0
  63. package/src/geometry-capture.ts +1098 -0
  64. package/src/gpu-class.ts +160 -0
  65. package/src/gpu-frame-observation.ts +424 -0
  66. package/src/gpu-readback.ts +143 -0
  67. package/src/gpu-scene-bvh.ts +464 -0
  68. package/src/grounding.ts +100 -0
  69. package/src/hot.ts +161 -0
  70. package/src/import-meta.d.ts +13 -0
  71. package/src/index.ts +1536 -0
  72. package/src/input.ts +690 -0
  73. package/src/instanced-batch-lod.ts +283 -0
  74. package/src/instanced-batch.ts +274 -0
  75. package/src/interpolation.ts +129 -0
  76. package/src/launch-diagnostics.ts +161 -0
  77. package/src/loop.ts +564 -0
  78. package/src/matrix-world.ts +245 -0
  79. package/src/merge-parts.ts +812 -0
  80. package/src/model-lod.ts +1315 -0
  81. package/src/net-protocol.ts +333 -0
  82. package/src/net-session.ts +477 -0
  83. package/src/net.ts +80 -0
  84. package/src/ocean/fft.ts +72 -0
  85. package/src/ocean/spectral.ts +728 -0
  86. package/src/particle-significance.ts +102 -0
  87. package/src/particles.ts +648 -0
  88. package/src/path-follow.ts +175 -0
  89. package/src/picking.ts +250 -0
  90. package/src/pipeline-census.ts +1566 -0
  91. package/src/platform.ts +210 -0
  92. package/src/playtest.ts +839 -0
  93. package/src/pointer-events.ts +411 -0
  94. package/src/pose-measure.ts +435 -0
  95. package/src/profiling/FrameCounters.ts +231 -0
  96. package/src/profiling/Spans.ts +548 -0
  97. package/src/profiling/opacity-convention.ts +21 -0
  98. package/src/profiling/render-list-validate.ts +175 -0
  99. package/src/profiling/render-trap-audit.ts +84 -0
  100. package/src/profiling/scene-warning.ts +190 -0
  101. package/src/profiling/span-probes.ts +191 -0
  102. package/src/profiling/unlit-foliage-warning.ts +149 -0
  103. package/src/projection-apply.ts +1529 -0
  104. package/src/projection-marker.ts +142 -0
  105. package/src/projection-plan.ts +1258 -0
  106. package/src/projection-skinned.ts +419 -0
  107. package/src/projection-stability.ts +409 -0
  108. package/src/projection-uniform.ts +328 -0
  109. package/src/random.ts +41 -0
  110. package/src/react-css.ts +604 -0
  111. package/src/react-glyphs.ts +114 -0
  112. package/src/react-host.ts +576 -0
  113. package/src/react-layout.ts +265 -0
  114. package/src/react.ts +60 -0
  115. package/src/render/alpha-antialiasing.ts +159 -0
  116. package/src/render/batched-velocity.ts +126 -0
  117. package/src/render/chain.ts +1021 -0
  118. package/src/render/daylight.ts +189 -0
  119. package/src/render/depth-pyramid.ts +596 -0
  120. package/src/render/foliage-alpha.ts +166 -0
  121. package/src/render/material-key.ts +60 -0
  122. package/src/render/mesh-pool.ts +144 -0
  123. package/src/render/probe-volume.ts +1668 -0
  124. package/src/render/resolution-subrect.ts +253 -0
  125. package/src/render/velocity.ts +442 -0
  126. package/src/render/virtual-shadow-pages.ts +827 -0
  127. package/src/render/virtual-shadow-partial.ts +174 -0
  128. package/src/render/virtual-shadow.ts +3330 -0
  129. package/src/render/world-impostor-surface.ts +722 -0
  130. package/src/render/world-impostor.ts +558 -0
  131. package/src/render-camera-cull.ts +441 -0
  132. package/src/render-pass-budget.ts +501 -0
  133. package/src/renderProjection.ts +758 -0
  134. package/src/renderer-config.ts +127 -0
  135. package/src/renderer.ts +1847 -0
  136. package/src/replay-protocol.ts +85 -0
  137. package/src/replay.ts +205 -0
  138. package/src/resolution-scaler.ts +819 -0
  139. package/src/rig-preparation.ts +271 -0
  140. package/src/ripple-field.ts +432 -0
  141. package/src/scale.ts +109 -0
  142. package/src/scene.ts +239 -0
  143. package/src/schedule.ts +155 -0
  144. package/src/skeletal-mesh.ts +61 -0
  145. package/src/skeleton.ts +100 -0
  146. package/src/snow-field.ts +744 -0
  147. package/src/softbody-topology.ts +269 -0
  148. package/src/softbody.ts +516 -0
  149. package/src/sprite-animator.ts +222 -0
  150. package/src/startup-readiness.ts +386 -0
  151. package/src/state.ts +66 -0
  152. package/src/static-transform.ts +274 -0
  153. package/src/storage-buffer.ts +253 -0
  154. package/src/streaming.ts +308 -0
  155. package/src/target-fps.ts +92 -0
  156. package/src/terrain-jobs-worker.ts +17 -0
  157. package/src/terrain-jobs.ts +353 -0
  158. package/src/textures.ts +39 -0
  159. package/src/tracers.ts +237 -0
  160. package/src/ui-bridge.ts +368 -0
  161. package/src/ui-hit-regions.ts +380 -0
  162. package/src/ui-layer.ts +83 -0
  163. package/src/ui-state.ts +220 -0
  164. package/src/version.ts +2 -0
  165. package/src/viewport.ts +253 -0
  166. package/src/warmup.ts +1357 -0
  167. package/src/water-surface.ts +384 -0
  168. package/src/wave-field.ts +524 -0
  169. package/src/world-capabilities.ts +131 -0
  170. package/src/world-cell-proxy.ts +392 -0
  171. package/src/world-cells.ts +10564 -0
  172. package/src/world-gpu-scene.ts +3354 -0
  173. package/src/world-heightmap.ts +82 -0
  174. package/src/world-package.ts +469 -0
  175. package/src/world-passes.ts +582 -0
  176. package/src/world-region.ts +17 -0
  177. package/src/world-terrain-splat.ts +564 -0
  178. package/src/world-tiles.ts +3826 -0
  179. package/src/world-topology.ts +370 -0
  180. package/src/world-validate.ts +48 -0
  181. package/src/world.ts +805 -0
  182. package/dist/gpu-readback-CMklJs6r.d.ts +0 -112
@@ -0,0 +1,1529 @@
1
+ import {
2
+ BatchedMesh,
3
+ type BufferGeometry,
4
+ type Color,
5
+ InstancedMesh,
6
+ LOD,
7
+ type Light,
8
+ Line,
9
+ LineLoop,
10
+ LineSegments,
11
+ type Material,
12
+ Matrix4,
13
+ Mesh,
14
+ type Object3D,
15
+ type PointLight,
16
+ Points,
17
+ Scene,
18
+ SkinnedMesh,
19
+ type SpotLight,
20
+ Sprite,
21
+ type SpriteMaterial,
22
+ } from "three";
23
+
24
+ import type { IGeometryOwnership } from "./geometry-capture.js";
25
+ import { MIN_BATCH_MEMBERS, isLight } from "./projection-plan.js";
26
+ import type {
27
+ IProjectionBatchGroup,
28
+ IProjectionExactEntry,
29
+ IProjectionMaterialGroup,
30
+ IProjectionProjectPlan,
31
+ IProjectionUniformGroup,
32
+ } from "./projection-plan.js";
33
+ import { SkinnedBatch, isSimilarityTransform } from "./projection-skinned.js";
34
+ import { baseColorOf, uniformUnchanged } from "./projection-uniform.js";
35
+ import {
36
+ disposeBatchedMeshVelocity,
37
+ ensureBatchedMeshVelocity,
38
+ isBatchedMeshVelocityPatched,
39
+ setBatchedMeshMatrixWithVelocity,
40
+ setBatchedMeshPreviousMatrix,
41
+ } from "./render/batched-velocity.js";
42
+ import type { ProjectionExactReason, ProjectionMaterialChecks } from "./renderProjection.js";
43
+
44
+ /**
45
+ * The apply-and-restore seam of the render projection (P2-3).
46
+ *
47
+ * Everything here mutates: batches are created and disposed, instance slots are handed out and
48
+ * recycled, stand-ins are built and dropped, lights are mirrored, and every source that left the
49
+ * authored scene is retired. The decision of what to do arrived as an immutable plan from
50
+ * `projection-plan.ts`; this module owns all of the state that doing it requires, and all of the
51
+ * restoration paths that undo it. Restoration is not optional bookkeeping — a slot that is not
52
+ * collapsed, a proxy that is not removed, or a light that outlives its source each draw something
53
+ * the game did not author.
54
+ */
55
+
56
+ /** A transform with no volume. Every triangle drawn through it is degenerate and discarded. */
57
+ const ZERO_MATRIX = /* @__PURE__ */ new Matrix4().multiplyScalar(0);
58
+
59
+ /**
60
+ * The material a uniform batch draws with: the group's representative with its base colour removed.
61
+ *
62
+ * `Color.setHex` converts sRGB into the working colour space as it decodes, so the components on the
63
+ * material are already linear. The instance colours are read from the same place and the node
64
+ * material multiplies the two, so leaving the shared colour at the identity leaves the drawn colour
65
+ * as the source colour, bit for bit, rather than a colour converted twice. Nothing here chooses a
66
+ * colour: it takes the game's own and removes the one value the draw now carries per instance.
67
+ */
68
+ function whiteClone(source: Material): Material {
69
+ const clone = source.clone() as Material & { color?: Color };
70
+ clone.color?.setRGB(1, 1, 1);
71
+ return clone;
72
+ }
73
+
74
+ /**
75
+ * Headroom on every batch, so the common case of a game adding a few more props does not rebuild
76
+ * one. A batch that overflows anyway is rebuilt at its new size rather than dropping the object.
77
+ */
78
+ const BATCH_GROWTH = 1.5;
79
+ const BATCH_MIN_SLOTS = 16;
80
+
81
+ /**
82
+ * WebGPU's guaranteed minimum `maxStorageBufferBindingSize`. A skinned palette never binds more,
83
+ * so no device is asked for a limit it may not grant; rigs past it keep their own draw.
84
+ */
85
+ const PALETTE_BINDING_BYTES = 134_217_728;
86
+
87
+ /**
88
+ * PRD-238 measurement (2026-08-28, tn-web on NVIDIA/Turing, 3 paired runs, frames 226–899): the
89
+ * 4,096-member rung with 75% outside the frustum reported 4,097 → 1,025 scene draw submissions
90
+ * (culling off → on; the harness excludes one presentation draw) and render.p50 1.60 → 1.10 ms
91
+ * (median of the three p50s, −0.50 ms). Keep culling enabled; the verification record is
92
+ * `docs/verification/runtime-perf-state.md` under PRD-238.
93
+ */
94
+ const PER_OBJECT_FRUSTUM_CULLED = true;
95
+ const SORT_BATCH_OBJECTS = false;
96
+
97
+ /**
98
+ * How many uniform-batch members the drift sweep may examine in one frame (PRD-462).
99
+ *
100
+ * The check is what makes the colour lane's per-frame sync ten times the shared lane's: one
101
+ * `Object.values` and one compare per member per frame, measured at 1,126 ns a member, which is
102
+ * 4.61 ms of a 4,096-material frame's 7.5 ms reconcile. Most of those frames are proving that
103
+ * nothing moved, and a game that animates a material's roughness does so on a handful of frames,
104
+ * not on all of them. So the sweep visits this many member positions a frame and carries its
105
+ * cursor across frames: every material is proved within `ceil(members / this)` frames, and the
106
+ * worst case at L4@4,096 is 8 — reported as `materialCheckStaleFrames`, never assumed.
107
+ *
108
+ * 512 is measured, not round: it takes the check from 4.61 ms to ~0.58 ms a frame, which puts
109
+ * L4@4,096's reconcile (3.5 ms) clearly under Godot's 5.95 ms for the same rung, and a smaller
110
+ * budget buys nothing a game can see while lengthening the staleness every frame pays for.
111
+ */
112
+ const MATERIAL_CHECKS_PER_FRAME = 512;
113
+
114
+ interface IBatch {
115
+ readonly mesh: InstancedMesh;
116
+ readonly group: IProjectionBatchGroup;
117
+ readonly geometry: BufferGeometry;
118
+ readonly material: Material;
119
+ /**
120
+ * True when the members' materials differ only in base colour: `material` is then a clone this
121
+ * mirror owns, and the colour each member draws with lives in the batch's instance colours.
122
+ */
123
+ readonly uniform: boolean;
124
+ /** Source object per instance slot, so a released slot can be reused rather than leaked. */
125
+ readonly instances: Map<Object3D, number>;
126
+ readonly free: number[];
127
+ /** Slots handed out so far, which is also where the next unused one begins. */
128
+ used: number;
129
+ capacity: number;
130
+ /** Whether an instance matrix was written this frame, so the upload is flagged once per batch. */
131
+ dirty: boolean;
132
+ /** Whether an instance colour was written this frame, flagged once per batch for the same reason. */
133
+ colorsDirty: boolean;
134
+ }
135
+
136
+ /**
137
+ * The material-keyed batch: many distinct geometries packed under one material.
138
+ *
139
+ * Unlike `IBatch` this owns copies of vertex data — that is what lets it fold geometries the
140
+ * instanced lane cannot — and so it carries the obligations a copy brings: budgets sized from the
141
+ * whole group before anything is built, a rebuild whenever the group's geometry set changes
142
+ * (`builtRevision` against the group's), and the scan's stream watch demoting any geometry whose
143
+ * versions move after admission. Slots are instance ids exactly as on the instanced lane: hidden
144
+ * rather than deleted when released, so the free list recycles them without touching the batch.
145
+ */
146
+ interface IBatched {
147
+ readonly mesh: BatchedMesh;
148
+ readonly group: IProjectionMaterialGroup;
149
+ readonly material: Material;
150
+ /** Source geometry to its packed sub-geometry id. */
151
+ readonly geometries: Map<BufferGeometry, number>;
152
+ /** Source object per instance slot, so a released slot can be reused rather than leaked. */
153
+ readonly instances: Map<Object3D, number>;
154
+ readonly free: number[];
155
+ /** Instance ids handed out so far, which is also where the next unused one begins. */
156
+ used: number;
157
+ capacity: number;
158
+ builtRevision: number;
159
+ }
160
+
161
+ /** What the mirror last knew about a source, so an unchanged source costs a compare and no work. */
162
+ interface ISourceState {
163
+ readonly matrixWorld: Matrix4;
164
+ visible: boolean;
165
+ geometry: BufferGeometry | undefined;
166
+ material: Material | Material[] | undefined;
167
+ /** The batch this source is an instance of, so a lane change releases the old slot directly. */
168
+ batch: IBatch | IBatched | SkinnedBatch;
169
+ /**
170
+ * The instance colour last written for this source, as three components. `NaN` on a fresh slot so
171
+ * the first write always happens — a colour that is genuinely `NaN` is not a colour three draws.
172
+ */
173
+ red: number;
174
+ green: number;
175
+ blue: number;
176
+ }
177
+
178
+ function exactObject(entry: IProjectionExactEntry): Object3D {
179
+ if (entry.object === undefined)
180
+ throw new Error("Projection exact entry was cleared before apply.");
181
+ return entry.object;
182
+ }
183
+
184
+ /**
185
+ * A stand-in of the same class as its source, with none of its children.
186
+ *
187
+ * Constructed through the source's own constructor so an unusual `Mesh` subclass keeps whatever
188
+ * its class does at draw time, rather than being flattened into a plain `Mesh` that merely looks
189
+ * like it.
190
+ */
191
+ function shallowProxy(object: Object3D): Object3D {
192
+ const source = object as Mesh & {
193
+ isInstancedMesh?: boolean;
194
+ isSkinnedMesh?: boolean;
195
+ isSprite?: boolean;
196
+ isPoints?: boolean;
197
+ isLine?: boolean;
198
+ isLineSegments?: boolean;
199
+ isLineLoop?: boolean;
200
+ isLOD?: boolean;
201
+ count?: number;
202
+ };
203
+ // Constructed by class, not by calling the source's constructor with no arguments.
204
+ //
205
+ // Calling it with none does not fail loudly, which is the problem. `new InstancedMesh()` builds
206
+ // happily with `count` undefined and a zero-length instance buffer — a stand-in that is an
207
+ // `InstancedMesh` by every type check and draws nothing. Nothing throws, nothing warns, and the
208
+ // instances are simply gone: the same shape of defect as the merge that dropped two of three
209
+ // instances, arrived at by a different route. What actually keeps them is
210
+ // `copySpecializedState` below; naming each class here is what makes the stand-in the right size
211
+ // to begin with rather than relying on that repair.
212
+ if (source.isInstancedMesh === true) {
213
+ return new InstancedMesh(source.geometry, source.material as Material, source.count ?? 1);
214
+ }
215
+ if (source.isSkinnedMesh === true) return new SkinnedMesh(source.geometry, source.material);
216
+ if (source.isSprite === true) return new Sprite(source.material as SpriteMaterial);
217
+ if (source.isPoints === true) return new Points(source.geometry, source.material);
218
+ // `LineSegments` and `LineLoop` both set `isLine`, so the flag alone would flatten either into
219
+ // a plain `Line` and draw its separate segments joined end to end.
220
+ if (source.isLineSegments === true) return new LineSegments(source.geometry, source.material);
221
+ if (source.isLineLoop === true) return new LineLoop(source.geometry, source.material);
222
+ if (source.isLine === true) return new Line(source.geometry, source.material);
223
+ if (source.isLOD === true) return new LOD();
224
+ return new Mesh(source.geometry, source.material);
225
+ }
226
+
227
+ /**
228
+ * Copies the state that makes a specialized mesh the thing it is.
229
+ *
230
+ * Shared by reference wherever three.js allows it, so the game animating a skeleton or writing an
231
+ * instance matrix drives what actually draws rather than a copy that stopped tracking it.
232
+ */
233
+ function copySpecializedState(source: Object3D, target: Object3D): void {
234
+ const from = source as SkinnedMesh & InstancedMesh & Mesh;
235
+ const to = target as SkinnedMesh & InstancedMesh & Mesh;
236
+ if ((from as { isInstancedMesh?: boolean }).isInstancedMesh === true) {
237
+ to.count = from.count;
238
+ to.instanceMatrix = from.instanceMatrix;
239
+ to.instanceColor = from.instanceColor;
240
+ }
241
+ if ((from as { isSkinnedMesh?: boolean }).isSkinnedMesh === true) {
242
+ // The game's own skeleton, so the bones it animates are the bones that deform this draw.
243
+ to.skeleton = from.skeleton;
244
+ to.bindMatrix = from.bindMatrix;
245
+ to.bindMatrixInverse = from.bindMatrixInverse;
246
+ to.bindMode = from.bindMode;
247
+ }
248
+ // Shared, not copied: a game writing `influences[0] = t` every frame writes into this array.
249
+ to.morphTargetInfluences = from.morphTargetInfluences;
250
+ to.morphTargetDictionary = from.morphTargetDictionary;
251
+ }
252
+
253
+ /**
254
+ * The mirror itself: the private scene the renderer is handed while the projection holds, plus
255
+ * every batch, slot table, stand-in and mirrored light behind it.
256
+ *
257
+ * Constructed and driven only by `SceneRenderProjection`, which keeps the public API, the report
258
+ * assembly and the deoptimization verdict; everything that touches renderer-owned state lives
259
+ * here, so the mutation boundary is one class and restoration has exactly one owner.
260
+ */
261
+ export class ProjectionMirror {
262
+ /** Handed to the renderer whenever the projection is faithful. Never shown to the game. */
263
+ readonly scene = new Scene();
264
+ readonly #batches = new Map<IProjectionBatchGroup, IBatch>();
265
+ readonly #materialBatches = new Map<IProjectionMaterialGroup, IBatched>();
266
+ readonly #skinnedBatches = new Map<IProjectionBatchGroup, SkinnedBatch>();
267
+ readonly #state = new Map<Object3D, ISourceState>();
268
+ /** Exact-lane stand-ins, keyed by the source they mirror. */
269
+ readonly #proxies = new Map<Object3D, Object3D>();
270
+ readonly #lightProxies = new Map<Light, Light>();
271
+ /**
272
+ * Each source light's own `shadow.autoUpdate`, captured the frame the mirror took that light's
273
+ * map offline.
274
+ *
275
+ * While the mirror is what draws, the authored scene is not rendered, so the authored light's
276
+ * shadow map is never sampled: three builds a render's lighting from the scene it is handed,
277
+ * which holds the clone, not the source. The clone carries its own `LightShadow` and keeps
278
+ * updating; the source's map is dead work. Three reads `shadow.autoUpdate` per light in
279
+ * `ShadowNode.updateBefore`, so switching the source's off drops that map without touching the
280
+ * shadow camera, map size, bias or flags. The exact authored value comes back in `releaseAll`.
281
+ */
282
+ readonly #lightShadowAutoUpdate = new Map<Light, boolean>();
283
+ readonly #exact = new Map<ProjectionExactReason, number>();
284
+ readonly #exactLane: IProjectionExactEntry[] = [];
285
+ readonly #extraExactPool: IProjectionExactEntry[] = [];
286
+ readonly #lightMembership = new WeakMap<Light, number>();
287
+ #lightGeneration = 0;
288
+ #exactLaneCount = 0;
289
+ #extraExactCount = 0;
290
+ #projectedObjects = 0;
291
+ #compileMs = 0;
292
+ #velocityEnabled: boolean;
293
+ /** Set when a member left a uniform group because its material drifted; read once per frame. */
294
+ #reclassified = false;
295
+ readonly #materialChecks: ProjectionMaterialChecks;
296
+ /** Where the drift sweep resumes: the group and the member offset within it. Persists frames. */
297
+ #sweepGroup = 0;
298
+ #sweepMember = 0;
299
+ /** Uniform members the plan holds, which is what the sweep walks and the bound divides. */
300
+ #sweepTotal = 0;
301
+ /**
302
+ * Materials already proved in the sweep in progress, so a material several members share is
303
+ * compared once per sweep rather than once per member. Bounded by the budget and cleared on
304
+ * every wrap, which is what makes the sweep's own cost a fixed number rather than a scene's.
305
+ */
306
+ readonly #swept = new Set<Material>();
307
+ /** Materials this frame's sweep found drifted; every member holding one leaves its group. */
308
+ readonly #drifted = new Set<Material>();
309
+
310
+ constructor(velocityEnabled = false, materialChecks: ProjectionMaterialChecks = "spread") {
311
+ this.#velocityEnabled = velocityEnabled;
312
+ this.#materialChecks = materialChecks;
313
+ }
314
+
315
+ /** Rebuilds the private mirror when a temporal chain turns per-object history on or off. */
316
+ setVelocityEnabled(enabled: boolean): boolean {
317
+ if (this.#velocityEnabled === enabled) return false;
318
+ this.releaseAll();
319
+ this.#velocityEnabled = enabled;
320
+ return true;
321
+ }
322
+
323
+ get projectedObjects(): number {
324
+ return this.#projectedObjects;
325
+ }
326
+
327
+ get batchCount(): number {
328
+ return this.#batches.size + this.#materialBatches.size + this.#skinnedBatches.size;
329
+ }
330
+
331
+ /** Batches on the skinned lane — rigs sharing a geometry and material drawn from one palette. */
332
+ get skinnedBatchCount(): number {
333
+ return this.#skinnedBatches.size;
334
+ }
335
+
336
+ /** Batches on the instanced lane — one shared geometry instance folded into an `InstancedMesh`. */
337
+ get instancedBatchCount(): number {
338
+ return this.#batches.size;
339
+ }
340
+
341
+ /** Batches on the material lane — differing geometries packed into one `BatchedMesh` per material. */
342
+ get materialBatchCount(): number {
343
+ return this.#materialBatches.size;
344
+ }
345
+
346
+ get proxyCount(): number {
347
+ return this.#proxies.size;
348
+ }
349
+
350
+ get exactCounts(): ReadonlyMap<ProjectionExactReason, number> {
351
+ return this.#exact;
352
+ }
353
+
354
+ get compileMs(): number {
355
+ return this.#compileMs;
356
+ }
357
+
358
+ /**
359
+ * True when this frame's apply found a member whose material no longer matched the draw it was an
360
+ * instance of. The frame is still correct — that member is now drawn exactly — but the
361
+ * classification that put it there is stale, so the caller re-derives it before the next frame
362
+ * draws. Read once per frame, after `apply`.
363
+ */
364
+ get reclassified(): boolean {
365
+ return this.#reclassified;
366
+ }
367
+
368
+ /** Which per-frame material check this mirror runs, for the report and the verdict line. */
369
+ get materialChecks(): ProjectionMaterialChecks {
370
+ return this.#materialChecks;
371
+ }
372
+
373
+ /** The per-frame ceiling on drift checks, or 0 when every material is proved every frame. */
374
+ get materialChecksPerFrame(): number {
375
+ return this.#materialChecks === "spread" ? MATERIAL_CHECKS_PER_FRAME : 0;
376
+ }
377
+
378
+ /**
379
+ * The worst frames a material edit can sit unproved for: one full sweep of the uniform members
380
+ * at the per-frame budget. 0 in `everyFrame` mode, where every material is proved every frame.
381
+ */
382
+ get materialCheckStaleFrames(): number {
383
+ if (this.#materialChecks === "everyFrame") return 0;
384
+ return Math.ceil(this.#sweepTotal / MATERIAL_CHECKS_PER_FRAME);
385
+ }
386
+
387
+ /**
388
+ * Proves a bounded slice of the uniform members' materials, resuming where the last frame stopped.
389
+ *
390
+ * The check itself is unchanged — `uniformUnchanged`, whole own-value list, component reads and
391
+ * `defines` walk. What is bounded is how many members pay for it this frame, and a member whose
392
+ * material is proved drifted is marked here so the loop below ejects every member holding it, in
393
+ * this same frame, exactly as an eager per-member check would have.
394
+ *
395
+ * Deduplicated per sweep rather than per member: a material sixty-four cubes share is one fact,
396
+ * and comparing it sixty-four times a sweep is the cost this exists to remove. The cursor walks
397
+ * member *positions* and wraps, so a scene that grew or shrank mid-sweep still proves every
398
+ * member it currently holds within `ceil(members / budget)` frames.
399
+ */
400
+ #sweepDrift(plan: IProjectionProjectPlan): void {
401
+ this.#drifted.clear();
402
+ let total = 0;
403
+ for (let index = 0; index < plan.batchGroupCount; index += 1) {
404
+ const group = plan.batchGroups[index] as IProjectionBatchGroup;
405
+ if ((group as Partial<IProjectionUniformGroup>).uniform === true) total += group.memberCount;
406
+ }
407
+ this.#sweepTotal = total;
408
+ let group = this.#sweepGroup;
409
+ let member = this.#sweepMember;
410
+ // A plan that shrank under the cursor leaves it past the end, which is the same thing as a
411
+ // finished sweep: start the next one from the top.
412
+ if (group >= plan.batchGroupCount) {
413
+ group = 0;
414
+ member = 0;
415
+ this.#swept.clear();
416
+ }
417
+ let budget = MATERIAL_CHECKS_PER_FRAME;
418
+ while (budget > 0 && group < plan.batchGroupCount) {
419
+ const candidate = plan.batchGroups[group] as IProjectionBatchGroup;
420
+ if ((candidate as Partial<IProjectionUniformGroup>).uniform !== true) {
421
+ group += 1;
422
+ member = 0;
423
+ continue;
424
+ }
425
+ if (member >= candidate.memberCount) {
426
+ group += 1;
427
+ member = 0;
428
+ continue;
429
+ }
430
+ const mesh = candidate.members[member] as Mesh;
431
+ const material = mesh.material as Material;
432
+ if (!this.#swept.has(material)) {
433
+ this.#swept.add(material);
434
+ if (!uniformUnchanged(material)) this.#drifted.add(material);
435
+ }
436
+ member += 1;
437
+ budget -= 1;
438
+ }
439
+ // Step past any group the last visited member exhausted, so a sweep that ends exactly on a
440
+ // slice boundary leaves the cursor on the next member rather than on a spent group — otherwise
441
+ // the next frame spends itself walking off the end and every material waits one frame longer
442
+ // than the bound the report states.
443
+ while (group < plan.batchGroupCount) {
444
+ const candidate = plan.batchGroups[group] as IProjectionBatchGroup;
445
+ if (
446
+ (candidate as Partial<IProjectionUniformGroup>).uniform === true &&
447
+ member < candidate.memberCount
448
+ )
449
+ break;
450
+ group += 1;
451
+ member = 0;
452
+ }
453
+ if (group < plan.batchGroupCount) {
454
+ this.#sweepGroup = group;
455
+ this.#sweepMember = member;
456
+ return;
457
+ }
458
+ // Off the end: the sweep covered every member, and the next one starts from the top with a
459
+ // fresh dedupe set rather than re-proving what this sweep just proved.
460
+ this.#swept.clear();
461
+ this.#sweepGroup = 0;
462
+ this.#sweepMember = 0;
463
+ }
464
+
465
+ /** Rebuilds exact-lane tallies and scratch from the scan without copying the entry objects. */
466
+ prepare(exactLane: readonly IProjectionExactEntry[], exactLaneCount: number): void {
467
+ this.#exact.clear();
468
+ this.#exactLaneCount = exactLaneCount;
469
+ this.#extraExactCount = 0;
470
+ for (let index = 0; index < exactLaneCount; index += 1) {
471
+ const entry = exactLane[index] as IProjectionExactEntry;
472
+ this.#exactLane[index] = entry;
473
+ const count = this.#exact.get(entry.reason) ?? 0;
474
+ this.#exact.set(entry.reason, count + 1);
475
+ }
476
+ }
477
+
478
+ /**
479
+ * Builds what a project plan describes and brings the mirror in line with the authored scene.
480
+ *
481
+ * Returns the unsupported-light reason when the scene's lights cannot be mirrored honestly —
482
+ * the caller then declines the whole frame. A batch that will not take an object gives up that
483
+ * object, not the scene: dropping several thousand batched props because one of them was
484
+ * awkward would be the fail-open rule applied at exactly the wrong granularity.
485
+ *
486
+ * `retireSources` is the sweep for objects that have left the scene, and a caller that has
487
+ * *proved* the scene's membership is unchanged — the projection's structure proof does exactly
488
+ * that — passes `false` and skips a per-instance walk that cannot find anything. Everything else
489
+ * here still runs: slots, stand-ins and lights are written every frame whatever the sweep does.
490
+ */
491
+ apply(plan: IProjectionProjectPlan, retireSources = true): string | undefined {
492
+ const lightFailure = this.#syncLights(plan.lights, plan.lightCount);
493
+ if (lightFailure !== undefined) {
494
+ this.releaseAll();
495
+ return lightFailure;
496
+ }
497
+ // Groups below the floor join the objects that were never eligible. They keep their own draw,
498
+ // which is what they had. The scratch entries are pooled because this is a per-frame path.
499
+ this.#extraExactCount = 0;
500
+ for (let index = 0; index < plan.belowFloorCount; index += 1) {
501
+ const mesh = plan.belowFloor[index] as Mesh;
502
+ this.#release(mesh);
503
+ this.#appendExact(mesh, "tooFewToBatch");
504
+ }
505
+ // A batch that will not take an object gives up that object, not the scene. Dropping several
506
+ // thousand batched props because one of them was awkward would be the fail-open rule applied
507
+ // at exactly the wrong granularity.
508
+ this.#projectedObjects = 0;
509
+ this.#reclassified = false;
510
+ // Before the member loops, because the loops read what it found: a member whose material this
511
+ // frame's slice proved drifted leaves the group here rather than at the next sweep's turn.
512
+ if (this.#materialChecks === "spread") this.#sweepDrift(plan);
513
+ for (let index = 0; index < plan.batchGroupCount; index += 1) {
514
+ const group = plan.batchGroups[index] as IProjectionBatchGroup;
515
+ const batch = this.#ensureBatch(group);
516
+ for (let member = 0; member < group.memberCount; member += 1) {
517
+ const mesh = group.members[member] as Mesh;
518
+ const refused =
519
+ batch === undefined ? "unsupportedGeometry" : this.#syncBatched(batch, mesh);
520
+ if (refused === undefined) {
521
+ this.#projectedObjects += 1;
522
+ continue;
523
+ }
524
+ // Each refusal names its own cause and every refused mesh keeps a draw of its own: a batch
525
+ // that will not take an object gives up that object, not the scene, and a member whose
526
+ // material drifted out of its group is drawn exactly until the classification catches up.
527
+ this.#release(mesh);
528
+ this.#appendExact(mesh, refused);
529
+ }
530
+ if (batch !== undefined) this.#flushBatch(batch);
531
+ }
532
+ this.#applyMaterialGroups(plan);
533
+ this.#applySkinnedGroups(plan);
534
+ for (let index = 0; index < this.#exactLaneCount; index += 1) {
535
+ const entry = this.#exactLane[index] as IProjectionExactEntry;
536
+ const object = exactObject(entry);
537
+ // An object can change lane while staying in the scene — a material turning transparent, a
538
+ // `renderOrder` being set, a plain mesh swapped for a skinned one. Its batch instance has to
539
+ // go as it acquires a proxy, or the frame draws it twice: once batched and once exactly.
540
+ this.#release(object);
541
+ this.#syncProxy(object);
542
+ }
543
+ if (retireSources) this.#retire(plan.seen, plan.lights, plan.lightCount);
544
+ // After retirement, so a slot freed this frame uploads collapsed rather than one frame late.
545
+ for (const batch of this.#skinnedBatches.values()) batch.end();
546
+ this.#clearExactScratch();
547
+ return undefined;
548
+ }
549
+
550
+ /**
551
+ * Applies the plan's skinned groups: one palette draw per group, each rig a slot re-posed from
552
+ * its own skeleton every frame.
553
+ *
554
+ * The world transform is folded into the palette, which is exact only for a similarity
555
+ * transform, so a rig scaled unevenly or mirrored keeps its own draw with that reason named.
556
+ */
557
+ #applySkinnedGroups(plan: IProjectionProjectPlan): void {
558
+ for (let index = 0; index < plan.skinnedGroupCount; index += 1) {
559
+ const group = plan.skinnedGroups[index] as IProjectionBatchGroup;
560
+ const batch = this.#ensureSkinned(group);
561
+ batch?.begin();
562
+ for (let member = 0; member < group.memberCount; member += 1) {
563
+ const rig = group.members[member] as SkinnedMesh;
564
+ const refused = batch === undefined ? "unsupportedGeometry" : this.#syncSkinned(batch, rig);
565
+ if (refused === undefined) {
566
+ this.#projectedObjects += 1;
567
+ continue;
568
+ }
569
+ this.#release(rig);
570
+ this.#appendExact(rig, refused);
571
+ }
572
+ }
573
+ }
574
+
575
+ /** Poses one rig in its palette slot, or names why it keeps a draw of its own. */
576
+ #syncSkinned(batch: SkinnedBatch, rig: SkinnedMesh): ProjectionExactReason | undefined {
577
+ if (!isSimilarityTransform(rig.matrixWorld.elements)) {
578
+ return rig.matrixWorld.determinant() <= 0 ? "negativeScale" : "nonUniformScale";
579
+ }
580
+ const slot = this.#claimSkinned(batch, rig);
581
+ if (slot === undefined) return "batchOverflow";
582
+ const state = this.#state.get(rig) as ISourceState;
583
+ const visible = this.#visibleInWorld(rig);
584
+ if (!visible) batch.hide(slot);
585
+ else {
586
+ // A rig coming back into view has collapsed history; it starts from its own pose.
587
+ if (!state.visible) batch.restart(slot);
588
+ batch.write(slot, rig);
589
+ }
590
+ state.visible = visible;
591
+ state.matrixWorld.copy(rig.matrixWorld);
592
+ state.material = rig.material;
593
+ return undefined;
594
+ }
595
+
596
+ #claimSkinned(batch: SkinnedBatch, rig: SkinnedMesh): number | undefined {
597
+ const previous = this.#state.get(rig);
598
+ if (previous !== undefined && previous.batch !== batch) this.#release(rig);
599
+ this.#releaseProxy(rig);
600
+ const known = batch.instances.has(rig);
601
+ const slot = batch.claim(rig);
602
+ if (slot === undefined) return undefined;
603
+ if (!known) {
604
+ this.#state.set(rig, {
605
+ matrixWorld: new Matrix4(),
606
+ visible: true,
607
+ geometry: rig.geometry,
608
+ material: rig.material,
609
+ batch,
610
+ red: Number.NaN,
611
+ green: Number.NaN,
612
+ blue: Number.NaN,
613
+ });
614
+ }
615
+ return slot;
616
+ }
617
+
618
+ /** The palette draw for one skinned group, rebuilt at a larger size when the group outgrows it. */
619
+ #ensureSkinned(group: IProjectionBatchGroup): SkinnedBatch | undefined {
620
+ const existing = this.#skinnedBatches.get(group);
621
+ if (existing !== undefined && existing.capacity >= group.memberCount) return existing;
622
+ const startedAt = globalThis.performance?.now() ?? 0;
623
+ const first = group.members[0] as SkinnedMesh;
624
+ const rigBytes = first.skeleton.bones.length * 64;
625
+ const capacity = Math.min(
626
+ Math.max(BATCH_MIN_SLOTS, Math.ceil(group.memberCount * BATCH_GROWTH)),
627
+ Math.floor(PALETTE_BINDING_BYTES / rigBytes),
628
+ );
629
+ if (existing !== undefined) {
630
+ if (existing.capacity >= capacity) return existing;
631
+ this.#disposeSkinned(existing);
632
+ }
633
+ let batch: SkinnedBatch;
634
+ try {
635
+ batch = new SkinnedBatch({ first, capacity, velocity: this.#velocityEnabled });
636
+ } catch {
637
+ return undefined;
638
+ }
639
+ this.#skinnedBatches.set(group, batch);
640
+ this.scene.add(batch.mesh);
641
+ this.#compileMs += (globalThis.performance?.now() ?? 0) - startedAt;
642
+ return batch;
643
+ }
644
+
645
+ #disposeSkinned(batch: SkinnedBatch): void {
646
+ for (const object of batch.instances.keys()) this.#state.delete(object);
647
+ batch.dispose();
648
+ for (const [group, candidate] of this.#skinnedBatches) {
649
+ if (candidate === batch) this.#skinnedBatches.delete(group);
650
+ }
651
+ }
652
+
653
+ #appendExact(object: Object3D, reason: ProjectionExactReason): void {
654
+ const index = this.#extraExactCount;
655
+ this.#extraExactCount += 1;
656
+ let entry = this.#extraExactPool[index];
657
+ if (entry === undefined) {
658
+ entry = { object, reason };
659
+ this.#extraExactPool.push(entry);
660
+ } else {
661
+ entry.object = object;
662
+ entry.reason = reason;
663
+ }
664
+ this.#exactLane[this.#exactLaneCount] = entry;
665
+ this.#exactLaneCount += 1;
666
+ const count = this.#exact.get(reason) ?? 0;
667
+ this.#exact.set(reason, count + 1);
668
+ }
669
+
670
+ /**
671
+ * Applies the plan's material-keyed groups: one `BatchedMesh` per group, its members as packed
672
+ * instances.
673
+ *
674
+ * `BatchedMesh.setMatrixAt` does not support negatively scaled matrices — a mirrored source
675
+ * would draw inside-out under front-face culling. The scan reads no world matrices by design,
676
+ * so the gate lives here where they are fresh. Counting viable members before building keeps
677
+ * the invariant that a projected frame never hands the renderer more draw candidates than the
678
+ * authored scene has: a group that cannot fill a batch never builds one.
679
+ */
680
+ #applyMaterialGroups(plan: IProjectionProjectPlan): void {
681
+ for (let index = 0; index < plan.materialGroupCount; index += 1) {
682
+ const group = plan.materialGroups[index] as IProjectionMaterialGroup;
683
+ if (this.#velocityEnabled && !isBatchedMeshVelocityPatched()) {
684
+ for (let member = 0; member < group.memberCount; member += 1) {
685
+ const mesh = group.members[member] as Mesh;
686
+ this.#release(mesh);
687
+ this.#appendExact(mesh, "batchVelocityPatchMissing");
688
+ }
689
+ continue;
690
+ }
691
+ let viableCount = 0;
692
+ for (let member = 0; member < group.memberCount; member += 1) {
693
+ if ((group.members[member] as Mesh).matrixWorld.determinant() > 0) viableCount += 1;
694
+ }
695
+ const attempted = viableCount >= MIN_BATCH_MEMBERS;
696
+ const batch = attempted ? this.#ensureBatched(group) : undefined;
697
+ for (let member = 0; member < group.memberCount; member += 1) {
698
+ const mesh = group.members[member] as Mesh;
699
+ const mirrored = mesh.matrixWorld.determinant() <= 0;
700
+ if (batch !== undefined && !mirrored && this.#syncBatchedMaterial(batch, mesh)) {
701
+ this.#projectedObjects += 1;
702
+ continue;
703
+ }
704
+ // The same report discipline as the instanced loop: each refusal names its own cause,
705
+ // and every refused mesh keeps a draw of its own.
706
+ const reason = mirrored
707
+ ? "negativeScale"
708
+ : !attempted
709
+ ? "tooFewToBatch"
710
+ : batch === undefined
711
+ ? "unsupportedGeometry"
712
+ : "batchOverflow";
713
+ this.#release(mesh);
714
+ this.#appendExact(mesh, reason);
715
+ }
716
+ }
717
+ }
718
+
719
+ /**
720
+ * Who owns each object this mirror hands the renderer, built on demand for a diagnostic.
721
+ *
722
+ * The mirror is what the renderer sees, so a per-object cost report reading the authored scene
723
+ * would attribute the frame to objects that were never submitted. Keyed by the rendered object:
724
+ * an exact stand-in names its one source, a batch names every source it folded. Nothing is
725
+ * retained — the map is the caller's, and building it costs one pass over the live entries.
726
+ */
727
+ describeOwnership(): Map<Object3D, IGeometryOwnership> {
728
+ const ownership = new Map<Object3D, IGeometryOwnership>();
729
+ for (const [source, proxy] of this.#proxies) {
730
+ ownership.set(proxy, { kind: "exact", sources: [source] });
731
+ }
732
+ for (const batch of this.#batches.values()) {
733
+ ownership.set(batch.mesh, {
734
+ kind: "instancedBatch",
735
+ sources: [...batch.instances.keys()],
736
+ });
737
+ }
738
+ for (const batch of this.#materialBatches.values()) {
739
+ ownership.set(batch.mesh, {
740
+ kind: "materialBatch",
741
+ sources: [...batch.instances.keys()],
742
+ });
743
+ }
744
+ for (const batch of this.#skinnedBatches.values()) {
745
+ ownership.set(batch.mesh, {
746
+ kind: "instancedBatch",
747
+ sources: [...batch.instances.keys()],
748
+ });
749
+ }
750
+ return ownership;
751
+ }
752
+
753
+ /** Drops sources that have left the authored scene, so nothing draws what the game removed. */
754
+ #retire(
755
+ seen: { has(object: Object3D): boolean },
756
+ lights: readonly (Light | undefined)[],
757
+ lightCount: number,
758
+ ): void {
759
+ this.#retireBatches(seen);
760
+ this.#retireMaterialBatches(seen);
761
+ this.#retireSkinnedBatches(seen);
762
+ this.#retireProxies(seen);
763
+ this.#retireLights(lights, lightCount);
764
+ }
765
+
766
+ #retireBatches(seen: { has(object: Object3D): boolean }): void {
767
+ for (const batch of this.#batches.values()) {
768
+ for (const object of batch.instances.keys()) {
769
+ if (seen.has(object)) continue;
770
+ const slot = batch.instances.get(object) as number;
771
+ // Collapsed and returned to the free list rather than removed: an `InstancedMesh` has a
772
+ // fixed slot count, and recycling is what lets a level stream objects in and out without
773
+ // rebuilding its draws each time.
774
+ if (slot >= 0) {
775
+ batch.mesh.setMatrixAt(slot, ZERO_MATRIX);
776
+ batch.mesh.instanceMatrix.needsUpdate = true;
777
+ }
778
+ batch.instances.delete(object);
779
+ if (slot >= 0) batch.free.push(slot);
780
+ this.#state.delete(object);
781
+ }
782
+ if (batch.instances.size === 0) this.#disposeBatch(batch);
783
+ }
784
+ }
785
+
786
+ /** Retires material-keyed batches on the same hidden-not-deleted free-list discipline. */
787
+ #retireMaterialBatches(seen: { has(object: Object3D): boolean }): void {
788
+ for (const batch of this.#materialBatches.values()) {
789
+ for (const object of batch.instances.keys()) {
790
+ if (seen.has(object)) continue;
791
+ const slot = batch.instances.get(object) as number;
792
+ batch.mesh.setVisibleAt(slot, false);
793
+ batch.instances.delete(object);
794
+ batch.free.push(slot);
795
+ this.#state.delete(object);
796
+ }
797
+ if (batch.instances.size === 0) this.#disposeBatched(batch);
798
+ }
799
+ }
800
+
801
+ #retireSkinnedBatches(seen: { has(object: Object3D): boolean }): void {
802
+ for (const batch of this.#skinnedBatches.values()) {
803
+ for (const object of batch.instances.keys()) {
804
+ if (seen.has(object)) continue;
805
+ batch.release(object);
806
+ this.#state.delete(object);
807
+ }
808
+ if (batch.instances.size === 0) this.#disposeSkinned(batch);
809
+ }
810
+ }
811
+
812
+ #retireProxies(seen: { has(object: Object3D): boolean }): void {
813
+ for (const object of this.#proxies.keys()) {
814
+ if (seen.has(object)) continue;
815
+ const proxy = this.#proxies.get(object) as Object3D;
816
+ this.scene.remove(proxy);
817
+ this.#proxies.delete(object);
818
+ this.#state.delete(object);
819
+ }
820
+ }
821
+
822
+ #retireLights(lights: readonly (Light | undefined)[], lightCount: number): void {
823
+ this.#lightGeneration += 1;
824
+ for (let index = 0; index < lightCount; index += 1) {
825
+ const light = lights[index] as Light;
826
+ this.#lightMembership.set(light, this.#lightGeneration);
827
+ }
828
+ for (const light of this.#lightProxies.keys()) {
829
+ if (this.#lightMembership.get(light) === this.#lightGeneration) continue;
830
+ const proxy = this.#lightProxies.get(light) as Light;
831
+ this.scene.remove(proxy);
832
+ this.#lightProxies.delete(light);
833
+ // A light that leaves the mirror gets its shadow update back now, so a light that returns
834
+ // later is cloned from a source that still updates rather than from the offline state.
835
+ this.#restoreLightShadow(light);
836
+ }
837
+ }
838
+
839
+ /** Puts a source light's own shadow-update state back and forgets it. */
840
+ #restoreLightShadow(light: Light): void {
841
+ const original = this.#lightShadowAutoUpdate.get(light);
842
+ if (original === undefined) return;
843
+ this.#lightShadowAutoUpdate.delete(light);
844
+ const shadow = (light as Light & { shadow?: { autoUpdate: boolean } }).shadow;
845
+ if (shadow !== undefined) shadow.autoUpdate = original;
846
+ }
847
+
848
+ /**
849
+ * Mirrors the scene's lights.
850
+ *
851
+ * A light cannot be in two graphs at once and moving the game's own light into the mirror would
852
+ * be exactly the destructive rewrite this class exists to stop, so each is cloned once and then
853
+ * kept in step. Only what a game changes at runtime is synchronized; a light form this does not
854
+ * recognize returns false and the whole frame goes to the authored scene, because a scene lit
855
+ * differently from the way the game lit it is a wrong picture, not a slow one.
856
+ */
857
+ #syncLights(lights: readonly (Light | undefined)[], lightCount: number): string | undefined {
858
+ for (let index = 0; index < lightCount; index += 1) {
859
+ const light = lights[index] as Light;
860
+ let proxy = this.#lightProxies.get(light);
861
+ if (proxy === undefined) {
862
+ const cloned = light.clone() as Light & { target?: Object3D };
863
+ if (!isLight(cloned)) return `a ${light.type} could not be mirrored`;
864
+ // A spot or directional light aims at a target object that lives in the game's graph. The
865
+ // clone's own target is a fresh object at the origin, so the mirror would light a
866
+ // different direction; pointing the clone at the authored target keeps the aim.
867
+ const target = (light as Light & { target?: Object3D }).target;
868
+ if (target !== undefined) cloned.target = target;
869
+ cloned.matrixAutoUpdate = false;
870
+ proxy = cloned;
871
+ this.#lightProxies.set(light, cloned);
872
+ this.scene.add(cloned);
873
+ }
874
+ // The local matrix, for the same reason the mesh proxies use it: the renderer recomposes
875
+ // every child's `matrixWorld` from its local matrix, so a light written the other way lights
876
+ // the scene from the origin regardless of where the game put it.
877
+ proxy.matrix.copy(light.matrixWorld);
878
+ proxy.visible = light.visible;
879
+ proxy.intensity = light.intensity;
880
+ (proxy.color as Color | undefined)?.copy(light.color as Color);
881
+ proxy.castShadow = light.castShadow;
882
+ proxy.layers.mask = light.layers.mask;
883
+ // Cone and falloff are runtime surface too: a flashlight zoom or a muzzle-flash decay
884
+ // changes these per frame, and frozen first-frame values would render the scene lit
885
+ // differently than the game lit it.
886
+ if ((light as { isSpotLight?: boolean }).isSpotLight === true) {
887
+ const spot = light as SpotLight;
888
+ const spotProxy = proxy as SpotLight;
889
+ spotProxy.angle = spot.angle;
890
+ spotProxy.penumbra = spot.penumbra;
891
+ spotProxy.distance = spot.distance;
892
+ spotProxy.decay = spot.decay;
893
+ spotProxy.power = spot.power;
894
+ }
895
+ if ((light as { isPointLight?: boolean }).isPointLight === true) {
896
+ const point = light as PointLight;
897
+ const pointProxy = proxy as PointLight;
898
+ pointProxy.distance = point.distance;
899
+ pointProxy.decay = point.decay;
900
+ pointProxy.power = point.power;
901
+ }
902
+ // The clone above copied `autoUpdate` before it was switched off, so the drawn light keeps
903
+ // its shadow. Only the source — whose map nothing samples this frame — is taken offline.
904
+ const shadow = (light as Light & { shadow?: { autoUpdate: boolean } }).shadow;
905
+ if (
906
+ shadow !== undefined &&
907
+ shadow.autoUpdate === true &&
908
+ !this.#lightShadowAutoUpdate.has(light)
909
+ ) {
910
+ this.#lightShadowAutoUpdate.set(light, shadow.autoUpdate);
911
+ shadow.autoUpdate = false;
912
+ }
913
+ }
914
+ return undefined;
915
+ }
916
+ /**
917
+ * Puts an eligible mesh in a batch and keeps it there, in step with its source.
918
+ *
919
+ * The mirror holds the game's own geometry and material by reference, never a copy, so a game
920
+ * that recolours a material recolours every draw sharing it and a game that streams into a
921
+ * geometry changes what draws without the mirror being told anything at all. Nothing here
922
+ * decides how anything looks; it decides only which draw a thing is part of.
923
+ *
924
+ * This is where "the game may change anything at any time" is paid for. Each supported property
925
+ * is compared against what was last pushed and written in place when it differs — a moved object
926
+ * is a matrix write, a hidden one a collapsed matrix. Nothing rebuilds, which is what makes
927
+ * reconciling every frame affordable instead of guessing once at startup and being wrong for the
928
+ * rest of the session.
929
+ *
930
+ * A uniform batch is the one draw that cannot hold the game's material, because it stands for
931
+ * many of them. So the colour is the only value it writes per member, and every *other* value its
932
+ * shared clone was built from is proved unchanged first: a member that drifted leaves the group
933
+ * rather than draw with a roughness, a map or an alpha that is not its own. That is a
934
+ * reclassification rather than a fallback, so the caller is told and the next frame re-derives it.
935
+ *
936
+ * Which frame proves it is the mode's business, not the ejection's. `everyFrame` compares here
937
+ * for every member; `spread` compares a bounded slice of the members in `#sweepDrift` and reads
938
+ * its answer here, so a drifted material costs every member holding it the same frame it was
939
+ * found in, and costs a settled frame nothing.
940
+ */
941
+ #syncBatched(target: IBatch, mesh: Mesh): ProjectionExactReason | undefined {
942
+ const material = mesh.material as Material;
943
+ const geometry = mesh.geometry;
944
+ let state = this.#state.get(mesh);
945
+
946
+ // Read before the group comparison below, because a member whose material no longer matches
947
+ // the group is leaving whichever batch it holds: the one it is in would draw it with a
948
+ // roughness, a map or an alpha that is not its own.
949
+ if (
950
+ target.uniform &&
951
+ state !== undefined &&
952
+ (this.#materialChecks === "everyFrame"
953
+ ? !uniformUnchanged(material)
954
+ : this.#drifted.size > 0 && this.#drifted.has(material))
955
+ ) {
956
+ this.#reclassified = true;
957
+ this.#release(mesh);
958
+ return "materialChanged";
959
+ }
960
+ // A geometry, material or flag change moves the object to a different batch entirely, so the
961
+ // old slot is released and it re-enters as if it were new. The group identity covers the
962
+ // shadow flags and layer mask, which change nothing about where an object is but everything
963
+ // about which draw it may share. The release takes the state with it, and the slot is gone
964
+ // with it, so the allocation below is what refills both.
965
+ if (state !== undefined && state.batch !== target) {
966
+ this.#release(mesh);
967
+ state = undefined;
968
+ }
969
+ // A mesh that was on the exact lane last frame and is batchable now must not keep its
970
+ // stand-in, or it draws twice. A scene with no stand-ins is the common case, and this is a map
971
+ // probe per object per frame, so the empty check comes before it.
972
+ if (this.#proxies.size > 0) this.#releaseProxy(mesh);
973
+
974
+ let slot = target.instances.get(mesh);
975
+ if (slot === undefined) {
976
+ slot = target.free.pop();
977
+ if (slot === undefined) {
978
+ if (target.used >= target.capacity) return "batchOverflow";
979
+ slot = target.used;
980
+ target.used += 1;
981
+ }
982
+ target.instances.set(mesh, slot);
983
+ // Deliberately unequal to anything real, so the first reconcile below writes the matrix
984
+ // and the visibility rather than assuming the new slot already carries them.
985
+ state = {
986
+ matrixWorld: new Matrix4().multiplyScalar(0),
987
+ visible: !mesh.visible,
988
+ geometry,
989
+ material,
990
+ batch: target,
991
+ red: Number.NaN,
992
+ green: Number.NaN,
993
+ blue: Number.NaN,
994
+ };
995
+ this.#state.set(mesh, state);
996
+ }
997
+ const current = state as ISourceState;
998
+ // Ancestor visibility, not the object's own flag: a prop under a hidden group does not draw,
999
+ // and a batch has no hierarchy to inherit that from.
1000
+ const visible = this.#visibleInWorld(mesh);
1001
+ // three's `equals` is the element-wise compare, and a host keeping matrices outside the script
1002
+ // engine runs it in place instead of copying 32 numbers in.
1003
+ if (visible !== current.visible || !current.matrixWorld.equals(mesh.matrixWorld)) {
1004
+ current.matrixWorld.copy(mesh.matrixWorld);
1005
+ current.visible = visible;
1006
+ // An `InstancedMesh` has no per-instance visibility flag, so a hidden object is given a
1007
+ // collapsed transform. Every one of its triangles then has zero area and is discarded before
1008
+ // rasterisation — the same trick the pass this replaces used, and the only one available
1009
+ // that does not disturb the other instances.
1010
+ target.mesh.setMatrixAt(slot, visible ? mesh.matrixWorld : ZERO_MATRIX);
1011
+ // One flag per batch rather than one per object, applied by the caller: the buffer is
1012
+ // uploaded once whatever wrote into it, and a version bump per object is a setter call per
1013
+ // object for the same single upload.
1014
+ target.dirty = true;
1015
+ }
1016
+ if (target.uniform) {
1017
+ // The only per-member value a uniform draw carries, and the only one a game may move without
1018
+ // leaving the group: three floats against what this slot last carried. The shared clone's
1019
+ // colour is white, so what three's node material draws is the source colour exactly.
1020
+ const color = baseColorOf(material) as Color;
1021
+ if (current.red !== color.r || current.green !== color.g || current.blue !== color.b) {
1022
+ target.mesh.setColorAt(slot, color);
1023
+ current.red = color.r;
1024
+ current.green = color.g;
1025
+ current.blue = color.b;
1026
+ target.colorsDirty = true;
1027
+ }
1028
+ }
1029
+ current.geometry = geometry;
1030
+ current.material = material;
1031
+ current.batch = target;
1032
+ return undefined;
1033
+ }
1034
+
1035
+ /** Whether the game currently wants this object drawn, ancestors included. */
1036
+ #visibleInWorld(object: Object3D): boolean {
1037
+ // A host whose parents cost a call and an allocation each answers for the whole chain.
1038
+ const host = (object as { __tnVisibleInWorld?: () => boolean }).__tnVisibleInWorld;
1039
+ if (typeof host === "function") return host.call(object);
1040
+ for (let node: Object3D | null = object; node !== null; node = node.parent) {
1041
+ if (!node.visible) return false;
1042
+ }
1043
+ return true;
1044
+ }
1045
+
1046
+ /**
1047
+ * Ends a batch's frame: one upload flag and one draw count for every slot written into it.
1048
+ *
1049
+ * Both were per object before, and both are per buffer: `needsUpdate` is a version bump the
1050
+ * renderer reads once, whatever wrote into the array behind it, and `count` is the number of slots
1051
+ * the batch has handed out — which only the last object of the loop could state correctly anyway.
1052
+ */
1053
+ #flushBatch(batch: IBatch): void {
1054
+ batch.mesh.count = batch.used;
1055
+ if (batch.dirty) {
1056
+ batch.dirty = false;
1057
+ batch.mesh.instanceMatrix.needsUpdate = true;
1058
+ }
1059
+ if (!batch.colorsDirty) return;
1060
+ batch.colorsDirty = false;
1061
+ (batch.mesh.instanceColor as { needsUpdate: boolean }).needsUpdate = true;
1062
+ }
1063
+
1064
+ /**
1065
+ * The batch for one (geometry, material, flags) group, sized to hold it.
1066
+ *
1067
+ * `InstancedMesh` rather than `BatchedMesh`, and the difference is measured rather than
1068
+ * stylistic. Three's WebGPU backend has no multi-draw path: it walks a `BatchedMesh` and issues
1069
+ * one `drawIndexed` per sub-draw, so a thousand batched objects still cost a thousand draw
1070
+ * commands. An `InstancedMesh` is one draw command for the whole group. It also references the
1071
+ * game's geometry rather than copying it into a private buffer, so a game streaming into its own
1072
+ * attribute needs no re-upload here at all — the batch is already looking at the same array.
1073
+ *
1074
+ * The price is that a group must share one geometry, where a `BatchedMesh` can hold several. A
1075
+ * level of mixed props therefore gets one draw per distinct prop kind instead of one per
1076
+ * material, which on the workloads measured is still the overwhelming majority of the reduction.
1077
+ */
1078
+ #ensureBatch(group: IProjectionBatchGroup): IBatch | undefined {
1079
+ const existing = this.#batches.get(group);
1080
+ if (existing !== undefined && existing.capacity >= group.memberCount) return existing;
1081
+ const capacity = Math.max(BATCH_MIN_SLOTS, Math.ceil(group.memberCount * BATCH_GROWTH));
1082
+ const first = group.members[0] as Mesh;
1083
+ if (existing !== undefined) this.#disposeBatch(existing);
1084
+ return this.#createBatch(group, first, capacity);
1085
+ }
1086
+
1087
+ #createBatch(group: IProjectionBatchGroup, first: Mesh, capacity: number): IBatch | undefined {
1088
+ const startedAt = globalThis.performance?.now() ?? 0;
1089
+ const uniform = (group as Partial<IProjectionUniformGroup>).uniform === true;
1090
+ // A uniform group stands for many materials, so it cannot draw any of them: it draws a clone the
1091
+ // mirror owns, identical to the group's representative except that its base colour is white and
1092
+ // each instance carries its own. A clone rather than the representative because the
1093
+ // representative is the game's, and a recolour of it must not reach the shared draw — and
1094
+ // because the game's instance is still what 64 cubes hold, and one draw may not have 64 owners.
1095
+ const material = uniform
1096
+ ? whiteClone(first.material as Material)
1097
+ : (first.material as Material);
1098
+ let mesh: InstancedMesh;
1099
+ try {
1100
+ mesh = new InstancedMesh(first.geometry, material, capacity);
1101
+ } catch {
1102
+ return undefined;
1103
+ }
1104
+ // Every slot starts collapsed. A slot that is allocated but not yet written would otherwise
1105
+ // draw the geometry at the origin for one frame — a prop flashing at world zero on the frame
1106
+ // the batch grows.
1107
+ for (let slot = 0; slot < capacity; slot += 1) mesh.setMatrixAt(slot, ZERO_MATRIX);
1108
+ mesh.instanceMatrix.needsUpdate = true;
1109
+ // Allocates the buffer three fills with the identity, so only the slots a member actually claims
1110
+ // are ever written. Seeded from the clone's own colour, which is that identity: this is three's
1111
+ // allocation path, not a private buffer the renderer would not know to bind.
1112
+ if (uniform) mesh.setColorAt(0, (material as Material & { color: Color }).color);
1113
+ // The batch spans wherever its instances are, so a bounding test on the whole thing can only
1114
+ // ever answer "visible" and is pure cost.
1115
+ mesh.frustumCulled = false;
1116
+ // Carried from the sources rather than defaulted. The batch is one object to the renderer, so
1117
+ // these are the batch's, and every mesh in it agreed on them — that is what the group means.
1118
+ mesh.castShadow = first.castShadow;
1119
+ mesh.receiveShadow = first.receiveShadow;
1120
+ mesh.layers.mask = first.layers.mask;
1121
+ const batch: IBatch = {
1122
+ mesh,
1123
+ group,
1124
+ geometry: first.geometry,
1125
+ material,
1126
+ uniform,
1127
+ instances: new Map(),
1128
+ free: [],
1129
+ used: 0,
1130
+ capacity,
1131
+ dirty: false,
1132
+ colorsDirty: false,
1133
+ };
1134
+ this.#batches.set(group, batch);
1135
+ this.scene.add(mesh);
1136
+ this.#compileMs += (globalThis.performance?.now() ?? 0) - startedAt;
1137
+ return batch;
1138
+ }
1139
+
1140
+ /**
1141
+ * The batch for one material group, rebuilt whenever the group's geometry set or size outgrows it.
1142
+ *
1143
+ * `BatchedMesh` rather than a second instancing pass, and that is the whole point of the lane:
1144
+ * it holds *many geometries* under *one material*, which is what a town of unique buildings over
1145
+ * shared surfaces needs and what an `InstancedMesh` cannot hold. On three's WebGPU backend the
1146
+ * batch is walked as one render object — one pipeline and bind-group setup, one sort entry, no
1147
+ * per-source matrix pass — with a `drawIndexed` per packed sub-geometry inside it. The draw-count
1148
+ * win is counted from the scene the renderer walks, which is what `resultDrawCandidates` has
1149
+ * always measured.
1150
+ *
1151
+ * Unlike the instanced lane, the packed copies are obligations: budgets are summed from every
1152
+ * distinct geometry before construction so nothing overflows mid-build, and the scan's stream
1153
+ * watch demotes any geometry whose versions move — so a copy never outlives the data it was made
1154
+ * from by even one frame.
1155
+ */
1156
+ #ensureBatched(group: IProjectionMaterialGroup): IBatched | undefined {
1157
+ const startedAt = globalThis.performance?.now() ?? 0;
1158
+ const existing = this.#materialBatches.get(group);
1159
+ if (
1160
+ existing !== undefined &&
1161
+ existing.builtRevision === group.revision &&
1162
+ existing.capacity >= group.memberCount
1163
+ ) {
1164
+ return existing;
1165
+ }
1166
+ if (existing !== undefined) this.#disposeBatched(existing);
1167
+ const capacity = Math.max(BATCH_MIN_SLOTS, Math.ceil(group.memberCount * BATCH_GROWTH));
1168
+ // Sized from the whole group before anything is built; an overflow throw mid-build would
1169
+ // otherwise leave a half-packed batch to dispose around.
1170
+ let vertexBudget = 0;
1171
+ let indexBudget = 0;
1172
+ for (const geometry of group.geometries.keys()) {
1173
+ const position = geometry.getAttribute("position");
1174
+ const vertices = position === undefined ? 0 : position.count;
1175
+ vertexBudget += vertices;
1176
+ const index = geometry.getIndex();
1177
+ indexBudget += index === null ? vertices : index.count;
1178
+ }
1179
+ const reference = group.members[0] as Mesh;
1180
+ const indexed = reference.geometry.getIndex() !== null;
1181
+ let mesh: BatchedMesh;
1182
+ try {
1183
+ mesh = new BatchedMesh(
1184
+ capacity,
1185
+ Math.ceil(vertexBudget * BATCH_GROWTH),
1186
+ indexed ? Math.ceil(indexBudget * BATCH_GROWTH) : 0,
1187
+ group.material,
1188
+ );
1189
+ } catch {
1190
+ return undefined;
1191
+ }
1192
+ // A source with frustumCulled=false may have shader-displaced vertices outside its authored
1193
+ // bounds. Keep that member in a batch that never applies BatchedMesh's bound-based culling;
1194
+ // the planner makes the flag uniform for every member in this batch.
1195
+ mesh.perObjectFrustumCulled = PER_OBJECT_FRUSTUM_CULLED && group.frustumCulled;
1196
+ mesh.sortObjects = SORT_BATCH_OBJECTS;
1197
+ mesh.frustumCulled = false;
1198
+ if (this.#velocityEnabled) {
1199
+ ensureBatchedMeshVelocity(mesh);
1200
+ }
1201
+ // Carried from the sources, exactly as the instanced lane carries them: every member agreed,
1202
+ // because the flags are part of what keyed the group.
1203
+ mesh.castShadow = reference.castShadow;
1204
+ mesh.receiveShadow = reference.receiveShadow;
1205
+ mesh.layers.mask = reference.layers.mask;
1206
+ const batch: IBatched = {
1207
+ mesh,
1208
+ group,
1209
+ material: group.material,
1210
+ geometries: new Map(),
1211
+ instances: new Map(),
1212
+ free: [],
1213
+ used: 0,
1214
+ capacity,
1215
+ builtRevision: group.revision,
1216
+ };
1217
+ try {
1218
+ for (const geometry of group.geometries.keys()) {
1219
+ batch.geometries.set(geometry, mesh.addGeometry(geometry));
1220
+ }
1221
+ } catch {
1222
+ mesh.dispose();
1223
+ return undefined;
1224
+ }
1225
+ this.#materialBatches.set(group, batch);
1226
+ this.scene.add(mesh);
1227
+ this.#compileMs += (globalThis.performance?.now() ?? 0) - startedAt;
1228
+ return batch;
1229
+ }
1230
+
1231
+ /**
1232
+ * Puts an eligible mesh into its material-keyed batch and keeps it there, in step with its
1233
+ * source. Slot bookkeeping is the instanced lane's exactly — allocate once, then per-frame
1234
+ * matrix and visibility compares — with `setVisibleAt` doing natively what a collapsed matrix
1235
+ * does on the other lane.
1236
+ */
1237
+ #syncBatchedMaterial(target: IBatched, mesh: Mesh): boolean {
1238
+ const previous = this.#state.get(mesh);
1239
+ if (previous !== undefined && previous.batch !== target) this.#release(mesh);
1240
+ this.#releaseProxy(mesh);
1241
+
1242
+ let slot = target.instances.get(mesh);
1243
+ const newSlot = slot === undefined;
1244
+ if (slot === undefined) {
1245
+ if (target.used >= target.capacity) return false;
1246
+ const geometryId = target.geometries.get(mesh.geometry);
1247
+ // A geometry that joined the group after this batch was built cannot be packed into it
1248
+ // here; the revision bump routes the whole group through a rebuild next frame.
1249
+ if (geometryId === undefined) return false;
1250
+ try {
1251
+ slot = target.mesh.addInstance(geometryId);
1252
+ } catch {
1253
+ return false;
1254
+ }
1255
+ target.used += 1;
1256
+ target.instances.set(mesh, slot);
1257
+ this.#state.set(mesh, {
1258
+ // Deliberately unequal to anything real, so the first reconcile below writes the matrix
1259
+ // and the visibility rather than assuming the new slot already carries them.
1260
+ matrixWorld: new Matrix4().multiplyScalar(0),
1261
+ visible: !mesh.visible,
1262
+ geometry: mesh.geometry,
1263
+ material: mesh.material,
1264
+ batch: target,
1265
+ red: Number.NaN,
1266
+ green: Number.NaN,
1267
+ blue: Number.NaN,
1268
+ });
1269
+ }
1270
+
1271
+ const state = this.#state.get(mesh) as ISourceState;
1272
+ const visible = this.#visibleInWorld(mesh);
1273
+ const matrixChanged = !state.matrixWorld.equals(mesh.matrixWorld);
1274
+ if (visible !== state.visible || matrixChanged) {
1275
+ if (this.#velocityEnabled) {
1276
+ const previousMatrix =
1277
+ newSlot || (!state.visible && visible) ? mesh.matrixWorld : state.matrixWorld;
1278
+ setBatchedMeshMatrixWithVelocity(target.mesh, slot, mesh.matrixWorld, previousMatrix);
1279
+ } else target.mesh.setMatrixAt(slot, mesh.matrixWorld);
1280
+ state.matrixWorld.copy(mesh.matrixWorld);
1281
+ state.visible = visible;
1282
+ target.mesh.setVisibleAt(slot, visible);
1283
+ } else if (this.#velocityEnabled) {
1284
+ const previousMatrix =
1285
+ newSlot || (!state.visible && visible) ? mesh.matrixWorld : state.matrixWorld;
1286
+ setBatchedMeshPreviousMatrix(target.mesh, slot, previousMatrix);
1287
+ }
1288
+ state.geometry = mesh.geometry;
1289
+ state.material = mesh.material;
1290
+ state.batch = target;
1291
+ return true;
1292
+ }
1293
+
1294
+ /** Removes a batch from the mirror and releases the buffers it owns. */
1295
+ #disposeBatch(batch: IBatch): void {
1296
+ this.scene.remove(batch.mesh);
1297
+ // The instance matrices are the batch's own; the geometry and material are the game's and are
1298
+ // deliberately left alone — unless this is a uniform draw, where the material is the mirror's
1299
+ // own clone and nobody else's.
1300
+ batch.mesh.dispose();
1301
+ if (batch.uniform) batch.material.dispose();
1302
+ for (const object of batch.instances.keys()) this.#state.delete(object);
1303
+ this.#batches.delete(batch.group);
1304
+ }
1305
+
1306
+ /**
1307
+ * Removes a material-keyed batch from the mirror.
1308
+ *
1309
+ * `BatchedMesh.dispose()` releases the packed vertex/index copies and the instance textures the
1310
+ * batch owns; the source geometries were only read from, never adopted, and stay the game's.
1311
+ */
1312
+ #disposeBatched(batch: IBatched): void {
1313
+ this.scene.remove(batch.mesh);
1314
+ if (this.#velocityEnabled) disposeBatchedMeshVelocity(batch.mesh);
1315
+ batch.mesh.dispose();
1316
+ for (const object of batch.instances.keys()) this.#state.delete(object);
1317
+ this.#materialBatches.delete(batch.group);
1318
+ }
1319
+
1320
+ /**
1321
+ * Keeps an exact-lane stand-in in step with its source.
1322
+ *
1323
+ * The proxy shares the source's geometry and material by reference — it is the same buffer and
1324
+ * the same material instance, so a game recolouring the original recolours what draws — and
1325
+ * carries the composed world matrix rather than a hierarchy, because the hierarchy above it is
1326
+ * in the authored scene where it belongs.
1327
+ */
1328
+ #syncProxy(object: Object3D): void {
1329
+ let proxy = this.#proxies.get(object);
1330
+ let fresh = false;
1331
+ if (proxy === undefined) {
1332
+ // `Object3D.prototype.clone` would deep-copy children the mirror does not want; a shallow
1333
+ // stand-in of the same class is what an exact draw needs.
1334
+ proxy = shallowProxy(object);
1335
+ proxy.matrixAutoUpdate = false;
1336
+ this.#proxies.set(object, proxy);
1337
+ fresh = true;
1338
+ // An `LOD` picks one of its levels by distance every frame, and it does that on itself. Its
1339
+ // levels therefore have to hang off the stand-in, or nothing selects one and the mirror
1340
+ // draws whichever rung happened to be visible when it was built.
1341
+ this.#buildLevels(object, proxy);
1342
+ }
1343
+ const source = object as Mesh;
1344
+ const target = proxy as Mesh;
1345
+ target.geometry = source.geometry;
1346
+ target.material = source.material;
1347
+ copySpecializedState(object, proxy);
1348
+ // Written into the *local* matrix, not `matrixWorld`, and this is not a detail.
1349
+ //
1350
+ // The renderer calls `updateMatrixWorld()` on whatever scene it is handed. A `Scene` composes
1351
+ // its own matrix every frame, which sets `matrixWorldNeedsUpdate`, which forces every child to
1352
+ // recompute `matrixWorld` from its local matrix — so anything written straight into
1353
+ // `matrixWorld` is overwritten before a single triangle is drawn, and every proxy in the mirror
1354
+ // renders at the world origin. Writing the local matrix instead survives that recomputation,
1355
+ // because the mirror's root is an identity transform and `identity × matrix` is the world
1356
+ // matrix the source had.
1357
+ target.matrix.copy(object.matrixWorld);
1358
+ target.visible = this.#visibleInWorld(object);
1359
+ target.renderOrder = object.renderOrder;
1360
+ target.castShadow = object.castShadow;
1361
+ target.receiveShadow = object.receiveShadow;
1362
+ target.frustumCulled = object.frustumCulled;
1363
+ target.layers.mask = object.layers.mask;
1364
+ // Added only once it is fully populated, never before.
1365
+ //
1366
+ // A `SkinnedMesh` built by its constructor has no `skeleton` until one is assigned, and
1367
+ // three.js reads `skeleton.bones.length` while it compiles the shader for that object. A
1368
+ // stand-in that is visible to the renderer for even one frame between construction and
1369
+ // assignment throws there, per frame, for as long as the material stays uncompiled — which is
1370
+ // a torrent of console errors and no drawn character.
1371
+ if (fresh) this.scene.add(proxy);
1372
+ }
1373
+
1374
+ /**
1375
+ * Releases one source's instance without disturbing the rest of its batch.
1376
+ *
1377
+ * The batch is retained on the source state rather than found by searching every batch. Searching
1378
+ * is what makes a lane change cost the number of batches in the scene, and lane changes happen
1379
+ * per object per frame.
1380
+ */
1381
+ #release(object: Object3D): void {
1382
+ const state = this.#state.get(object);
1383
+ const batch = state === undefined ? undefined : state.batch;
1384
+ if (batch instanceof SkinnedBatch) {
1385
+ batch.release(object);
1386
+ this.#state.delete(object);
1387
+ return;
1388
+ }
1389
+ const slot = batch?.instances.get(object);
1390
+ if (batch !== undefined && slot !== undefined) {
1391
+ // Hidden or collapsed before the slot is handed back, so a freed slot draws nothing until
1392
+ // something else claims it. Reusing slots rather than rebuilding the batch is what keeps a
1393
+ // level that streams objects in and out from rebuilding its draws every time it does.
1394
+ if ((batch as IBatch).mesh.isInstancedMesh === true) {
1395
+ if (slot >= 0) {
1396
+ (batch as IBatch).mesh.setMatrixAt(slot, ZERO_MATRIX);
1397
+ (batch as IBatch).mesh.instanceMatrix.needsUpdate = true;
1398
+ }
1399
+ } else {
1400
+ (batch as IBatched).mesh.setVisibleAt(slot, false);
1401
+ }
1402
+ batch.instances.delete(object);
1403
+ if (slot >= 0) batch.free.push(slot);
1404
+ }
1405
+ this.#state.delete(object);
1406
+ }
1407
+
1408
+ /**
1409
+ * Gives an `LOD` stand-in the same levels, at the same distances, as the source.
1410
+ *
1411
+ * `LOD.update()` runs on the container and toggles its children by camera distance, so the
1412
+ * levels must be children of the stand-in for any of that to happen. Each level draws the
1413
+ * source's own geometry and material; only the container is new.
1414
+ */
1415
+ #buildLevels(object: Object3D, proxy: Object3D): void {
1416
+ if ((object as { isLOD?: boolean }).isLOD !== true) return;
1417
+ const source = object as LOD;
1418
+ const target = proxy as LOD;
1419
+ for (const level of source.levels) {
1420
+ const mesh = shallowProxy(level.object);
1421
+ copySpecializedState(level.object, mesh);
1422
+ mesh.matrix.copy(level.object.matrix);
1423
+ mesh.matrixAutoUpdate = false;
1424
+ target.addLevel(mesh, level.distance, level.hysteresis);
1425
+ }
1426
+ }
1427
+
1428
+ /** Drops an exact-lane stand-in, for a source that no longer needs one. */
1429
+ #releaseProxy(object: Object3D): void {
1430
+ const proxy = this.#proxies.get(object);
1431
+ if (proxy === undefined) return;
1432
+ this.scene.remove(proxy);
1433
+ this.#proxies.delete(object);
1434
+ }
1435
+
1436
+ #clearExactScratch(): void {
1437
+ for (let index = 0; index < this.#exactLaneCount; index += 1) {
1438
+ const entry = this.#exactLane[index] as IProjectionExactEntry;
1439
+ entry.object = undefined;
1440
+ }
1441
+ for (let index = 0; index < this.#extraExactPool.length; index += 1) {
1442
+ const entry = this.#extraExactPool[index] as IProjectionExactEntry;
1443
+ entry.object = undefined;
1444
+ }
1445
+ this.#exactLaneCount = 0;
1446
+ this.#extraExactCount = 0;
1447
+ }
1448
+
1449
+ /** Tears the mirror down, leaving the authored scene untouched, as it has been throughout. */
1450
+ releaseAll(): void {
1451
+ for (const batch of this.#batches.values()) {
1452
+ this.scene.remove(batch.mesh);
1453
+ batch.mesh.dispose();
1454
+ if (batch.uniform) batch.material.dispose();
1455
+ }
1456
+ this.#batches.clear();
1457
+ for (const batch of this.#materialBatches.values()) {
1458
+ this.scene.remove(batch.mesh);
1459
+ if (this.#velocityEnabled) disposeBatchedMeshVelocity(batch.mesh);
1460
+ batch.mesh.dispose();
1461
+ }
1462
+ this.#materialBatches.clear();
1463
+ for (const batch of this.#skinnedBatches.values()) batch.dispose();
1464
+ this.#skinnedBatches.clear();
1465
+ for (const proxy of this.#proxies.values()) this.scene.remove(proxy);
1466
+ this.#proxies.clear();
1467
+ for (const proxy of this.#lightProxies.values()) this.scene.remove(proxy);
1468
+ this.#lightProxies.clear();
1469
+ for (const light of this.#lightShadowAutoUpdate.keys()) this.#restoreLightShadow(light);
1470
+ this.#state.clear();
1471
+ this.#exact.clear();
1472
+ this.#clearExactScratch();
1473
+ this.#projectedObjects = 0;
1474
+ }
1475
+
1476
+ /**
1477
+ * What the mirror currently holds for one source object, or `undefined` if it holds nothing.
1478
+ *
1479
+ * Bounded diagnostics, for the load test and the unit tests: it answers "is this object being
1480
+ * drawn, on which lane, and with what transform and visibility" without exposing the batches or
1481
+ * the reconciliation state. Games never call this — there is no optimizer API in generated
1482
+ * source, and this class is not part of the package's public surface — but a benchmark that
1483
+ * cannot ask what the renderer was given can only report intent, and intent is not evidence.
1484
+ */
1485
+ inspect(
1486
+ object: Object3D,
1487
+ ): { lane: "batched" | "exact"; matrixWorld: Matrix4; visible: boolean } | undefined {
1488
+ const proxy = this.#proxies.get(object);
1489
+ if (proxy !== undefined) {
1490
+ return {
1491
+ lane: "exact",
1492
+ matrixWorld: new Matrix4().copy(proxy.matrix),
1493
+ visible: proxy.visible,
1494
+ };
1495
+ }
1496
+ const state = this.#state.get(object);
1497
+ if (state === undefined) return undefined;
1498
+ const batch = state.batch;
1499
+ const slot = batch?.instances.get(object);
1500
+ if (batch === undefined || slot === undefined) return undefined;
1501
+ const matrixWorld = new Matrix4();
1502
+ // Both lanes answer the same way; which primitive backs the batch is not the caller's business.
1503
+ if (batch instanceof SkinnedBatch) {
1504
+ matrixWorld.copy(state.matrixWorld);
1505
+ } else if ((batch as IBatch).mesh.isInstancedMesh === true && slot < 0) {
1506
+ matrixWorld.copy(state.matrixWorld);
1507
+ } else {
1508
+ batch.mesh.getMatrixAt(slot, matrixWorld);
1509
+ }
1510
+ return { lane: "batched", matrixWorld, visible: state.visible };
1511
+ }
1512
+
1513
+ /** True when some batch in the mirror draws with this exact material instance. */
1514
+ drawsWith(material: Material): boolean {
1515
+ for (const batch of this.#batches.values()) {
1516
+ if (batch.material === material) return true;
1517
+ }
1518
+ for (const batch of this.#materialBatches.values()) {
1519
+ if (batch.material === material) return true;
1520
+ }
1521
+ for (const batch of this.#skinnedBatches.values()) {
1522
+ if (batch.sourceMaterial === material) return true;
1523
+ }
1524
+ for (const proxy of this.#proxies.values()) {
1525
+ if ((proxy as Mesh).material === material) return true;
1526
+ }
1527
+ return false;
1528
+ }
1529
+ }