@threenative/core 0.3.11 → 0.3.13

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 (236) hide show
  1. package/README.md +1 -1
  2. package/capabilities.json +1988 -204
  3. package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
  4. package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
  5. package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
  6. package/dist/chunk-4SRAQFTU.js +133 -0
  7. package/dist/chunk-CFGTPFUH.js +231 -0
  8. package/dist/chunk-DIPIJICH.js +8916 -0
  9. package/dist/chunk-EEABDLUC.js +2237 -0
  10. package/dist/chunk-EFWZWLPY.js +1895 -0
  11. package/dist/chunk-GXY7B3JG.js +46 -0
  12. package/dist/chunk-GYUZJQ7U.js +280 -0
  13. package/dist/chunk-H4J6IAJE.js +504 -0
  14. package/dist/chunk-KIRUKTBQ.js +187 -0
  15. package/dist/chunk-QWJEMUUT.js +94 -0
  16. package/dist/chunk-SV4QVUTQ.js +31 -0
  17. package/dist/chunk-U4YHUKKL.js +615 -0
  18. package/dist/chunk-VP43GIWW.js +18 -0
  19. package/dist/chunk-XDTZ4QMO.js +160 -0
  20. package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
  21. package/dist/{game-DzMcitDO.d.ts → game-k8K3hZai.d.ts} +85 -9
  22. package/dist/hot.d.ts +5 -4
  23. package/dist/hot.js +5 -52
  24. package/dist/index.d.ts +633 -1351
  25. package/dist/index.js +12873 -23068
  26. package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-DPTzeCcD.d.ts} +35 -3
  27. package/dist/playtest.d.ts +5 -4
  28. package/dist/playtest.js +25 -75
  29. package/dist/quality-BYqKGAwo.d.ts +868 -0
  30. package/dist/react-css.js +1 -215
  31. package/dist/react.d.ts +3 -2
  32. package/dist/render-environment.d.ts +170 -0
  33. package/dist/render-environment.js +352 -0
  34. package/dist/{renderer-rZm0hVqq.d.ts → renderer-BtOSseYf.d.ts} +42 -35
  35. package/dist/spells/index.d.ts +643 -0
  36. package/dist/spells/index.js +1558 -0
  37. package/dist/spells/ultra/index.d.ts +1600 -0
  38. package/dist/spells/ultra/index.js +6804 -0
  39. package/dist/terrain-jobs-worker.js +1 -123
  40. package/dist/two-sided-foliage-W523J3UM.js +1 -0
  41. package/dist/ui-layer.js +6 -384
  42. package/dist/worker.js +13 -43
  43. package/dist/world.d.ts +988 -268
  44. package/dist/world.js +17464 -18290
  45. package/mcp/animation-server.mjs +1 -1
  46. package/mcp/animation.mjs +2 -3
  47. package/mcp/engine-server.mjs +245 -52
  48. package/mcp/servers.mjs +10 -3
  49. package/mcp/terrain.mjs +8 -0
  50. package/package.json +19 -7
  51. package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
  52. package/patches/three@0.187.0.patch +2004 -407
  53. package/src/animation-batch.ts +193 -0
  54. package/src/animation-layers.ts +7 -3
  55. package/src/animation.ts +209 -29
  56. package/src/asset-cache.ts +3 -3
  57. package/src/asset-memo.ts +202 -0
  58. package/src/assets.ts +437 -125
  59. package/src/auto-batch.ts +190 -44
  60. package/src/card-lod.ts +152 -0
  61. package/src/compressed-texture-preparation.ts +1008 -0
  62. package/src/compute-driven.ts +1 -1
  63. package/src/config.ts +8 -0
  64. package/src/debug.ts +103 -22
  65. package/src/dev-global.ts +54 -0
  66. package/src/engine-hooks.ts +37 -0
  67. package/src/frame-budget.ts +50 -23
  68. package/src/game-boot-phase.ts +269 -0
  69. package/src/game-dev-tools.ts +86 -0
  70. package/src/game-frame-loop.ts +958 -0
  71. package/src/game-renderer-metrics.ts +77 -0
  72. package/src/game-startup.ts +1076 -0
  73. package/src/game-ui.ts +84 -0
  74. package/src/game-validate.ts +70 -0
  75. package/src/game.ts +198 -2264
  76. package/src/gamepad-mappings.ts +269 -0
  77. package/src/generated/console-markers.ts +13 -0
  78. package/src/geometry-capture.ts +28 -4
  79. package/src/gpu-readings.ts +98 -0
  80. package/src/gpu-scene-bvh.ts +149 -36
  81. package/src/hot.ts +4 -7
  82. package/src/index.ts +141 -9
  83. package/src/input.ts +237 -25
  84. package/src/instanced-batch-lod.ts +3 -8
  85. package/src/interpolation.ts +171 -40
  86. package/src/launch-diagnostics.ts +22 -12
  87. package/src/look/ao-admission.ts +25 -0
  88. package/src/look/auto-exposure.ts +5 -16
  89. package/src/look/default-tone-mapping.ts +41 -5
  90. package/src/look/filmic-tone-mapping.ts +15 -13
  91. package/src/look/local-exposure.ts +2 -7
  92. package/src/look/look-diagnostics.ts +3 -3
  93. package/src/look/quad-pass.ts +21 -0
  94. package/src/look/quality.ts +14 -5
  95. package/src/look/unreal-bloom.ts +4 -13
  96. package/src/look/world-environment.ts +113 -103
  97. package/src/loop.ts +29 -0
  98. package/src/merge-parts.ts +20 -24
  99. package/src/model-lod.ts +139 -17
  100. package/src/particle-kinds.ts +515 -0
  101. package/src/particle-significance.ts +12 -0
  102. package/src/particles.ts +19 -10
  103. package/src/picking.ts +17 -3
  104. package/src/platform.ts +23 -4
  105. package/src/playtest.ts +27 -1
  106. package/src/profiling/FrameStages.ts +5 -6
  107. package/src/profiling/Spans.ts +3 -17
  108. package/src/profiling/debug-telemetry.ts +2 -6
  109. package/src/profiling/render-list-validate.ts +6 -15
  110. package/src/projection-apply.ts +4 -1
  111. package/src/projection-marker.ts +2 -1
  112. package/src/projection-plan.ts +9 -6
  113. package/src/quiet-markers.ts +3 -10
  114. package/src/render/cpu-bvh.ts +100 -0
  115. package/src/render/depth-pyramid.ts +6 -14
  116. package/src/render/environment/environmentContribution.ts +202 -0
  117. package/src/render/environment/environmentRadiance.ts +44 -0
  118. package/src/render/environment/environmentSampleCache.ts +56 -0
  119. package/src/render/environment/environmentSampling.ts +201 -0
  120. package/src/render/environment/environmentSnapshot.ts +71 -0
  121. package/src/render/environment/gate.ts +57 -0
  122. package/src/render/mesh-pool.ts +4 -20
  123. package/src/render/probe-trace.ts +872 -0
  124. package/src/render/probe-volume.ts +780 -34
  125. package/src/render/radiance-cache.ts +17 -0
  126. package/src/render/resolution-subrect.ts +2 -0
  127. package/src/render/rough-diffuse.ts +46 -12
  128. package/src/render/soft-shadow.ts +27 -12
  129. package/src/render/virtual-shadow-adaptive.ts +55 -0
  130. package/src/render/virtual-shadow-casters.ts +175 -0
  131. package/src/render/virtual-shadow-layers.ts +76 -0
  132. package/src/render/virtual-shadow-level.ts +224 -0
  133. package/src/render/virtual-shadow-markers.ts +193 -0
  134. package/src/render/virtual-shadow-options.ts +370 -0
  135. package/src/render/virtual-shadow-pages.ts +5 -0
  136. package/src/render/virtual-shadow-partial.ts +13 -0
  137. package/src/render/virtual-shadow.ts +231 -1008
  138. package/src/render/world-impostor-surface.ts +402 -40
  139. package/src/render/world-impostor.ts +5 -2
  140. package/src/render-camera-cull.ts +98 -3
  141. package/src/render-environment.ts +41 -0
  142. package/src/render-pass-budget.ts +34 -7
  143. package/src/renderProjection.ts +22 -0
  144. package/src/renderer-config.ts +36 -0
  145. package/src/renderer-facts.ts +37 -0
  146. package/src/renderer.ts +144 -65
  147. package/src/resolution-scaler.ts +3 -2
  148. package/src/scene-entry-inspectors.ts +61 -0
  149. package/src/snow-field.ts +2 -1
  150. package/src/spells/cast-pool.ts +361 -0
  151. package/src/spells/index.ts +177 -0
  152. package/src/spells/mechanisms.ts +295 -0
  153. package/src/spells/reaction-field.ts +415 -0
  154. package/src/spells/spell-lights.ts +139 -0
  155. package/src/spells/spell-world.ts +187 -0
  156. package/src/spells/spell.ts +397 -0
  157. package/src/spells/spells.ts +283 -0
  158. package/src/spells/ultra/engine/camera.ts +184 -0
  159. package/src/spells/ultra/engine/quality.ts +96 -0
  160. package/src/spells/ultra/index.ts +52 -0
  161. package/src/spells/ultra/main.ts +305 -0
  162. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  163. package/src/spells/ultra/spells/cast.ts +233 -0
  164. package/src/spells/ultra/spells/fire.ts +1267 -0
  165. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  166. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  167. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  168. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  169. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  170. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  171. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  172. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  173. package/src/spells/ultra/vfx/common.ts +1195 -0
  174. package/src/spells/ultra/vfx/noise.ts +441 -0
  175. package/src/startup-offscreen-bytes.ts +78 -0
  176. package/src/startup-readiness.ts +128 -34
  177. package/src/static-transform.ts +25 -19
  178. package/src/streamed-textures.ts +112 -0
  179. package/src/streaming.ts +68 -4
  180. package/src/texture-streaming.ts +331 -0
  181. package/src/version.ts +1 -1
  182. package/src/warmup.ts +56 -8
  183. package/src/water-surface.ts +9 -3
  184. package/src/worker.ts +12 -2
  185. package/src/world-bundle-safety.ts +446 -0
  186. package/src/world-cell-batches.ts +1178 -0
  187. package/src/world-cell-chunks.ts +1128 -0
  188. package/src/world-cell-data.ts +995 -0
  189. package/src/world-cell-impostors.ts +1461 -0
  190. package/src/world-cell-lod-bias.ts +151 -0
  191. package/src/world-cell-models.ts +1074 -0
  192. package/src/world-cell-options.ts +177 -0
  193. package/src/world-cell-placements.ts +798 -0
  194. package/src/world-cell-prewarm.ts +592 -0
  195. package/src/world-cell-readiness.ts +357 -0
  196. package/src/world-cell-records.ts +401 -0
  197. package/src/world-cell-render-bundles.ts +459 -0
  198. package/src/world-cell-render-gpu-dress.ts +710 -0
  199. package/src/world-cell-render-main-cull.ts +540 -0
  200. package/src/world-cell-render-shadow-claims.ts +198 -0
  201. package/src/world-cell-render-util.ts +259 -0
  202. package/src/world-cell-render.ts +1501 -0
  203. package/src/world-cell-residency.ts +754 -0
  204. package/src/world-cell-stale.ts +238 -0
  205. package/src/world-cells.ts +1335 -10418
  206. package/src/world-chunk-shadow.ts +308 -0
  207. package/src/world-collar.ts +315 -0
  208. package/src/world-gpu-flags.ts +131 -0
  209. package/src/world-gpu-readback.ts +881 -0
  210. package/src/world-gpu-reference.ts +524 -0
  211. package/src/world-gpu-scene.ts +256 -2286
  212. package/src/world-gpu-shadow.ts +203 -0
  213. package/src/world-gpu-types.ts +409 -0
  214. package/src/world-gpu-validation.ts +518 -0
  215. package/src/world-heightfield.ts +802 -0
  216. package/src/world-load-limiter.ts +111 -0
  217. package/src/world-model-sections.ts +80 -0
  218. package/src/world-noise.ts +241 -0
  219. package/src/world-package.ts +42 -0
  220. package/src/world-region.ts +1 -1
  221. package/src/world-river-ribbon.ts +282 -0
  222. package/src/world-root-frame.ts +39 -0
  223. package/src/world-shore-field.ts +91 -0
  224. package/src/world-static-pose.ts +163 -0
  225. package/src/world-surface-sampler.ts +48 -0
  226. package/src/world-terrain-splat.ts +361 -153
  227. package/src/world-tile-budget.ts +249 -0
  228. package/src/world-tile-geometry.ts +469 -0
  229. package/src/world-tile-lod.ts +408 -0
  230. package/src/world-tile-observation.ts +566 -0
  231. package/src/world-tile-stitch.ts +166 -0
  232. package/src/world-tiles.ts +247 -1755
  233. package/src/world-validate.ts +6 -14
  234. package/src/world-warm.ts +51 -0
  235. package/src/world-water-bodies.ts +359 -0
  236. package/src/world.ts +48 -741
package/src/model-lod.ts CHANGED
@@ -4,6 +4,7 @@ import {
4
4
  BufferGeometry,
5
5
  type Camera,
6
6
  Group,
7
+ InstancedMesh,
7
8
  Matrix4,
8
9
  type Mesh,
9
10
  Object3D,
@@ -11,6 +12,7 @@ import {
11
12
  Vector3,
12
13
  } from "three";
13
14
  import { pixelsPerUnit } from "./clustered-mesh.js";
15
+ import type { attachInstancedLod } from "./instanced-batch-lod.js";
14
16
 
15
17
  /**
16
18
  * Engine-owned detail selection for automatic discrete LOD (`TN_discrete_lod`).
@@ -128,6 +130,16 @@ export function biasedLodDistance(distance: number): number {
128
130
 
129
131
  const nearest = new Vector3();
130
132
 
133
+ /**
134
+ * The near plane a caller with no camera `near` uses for the degenerate test.
135
+ *
136
+ * `degenerate` is whether the sphere's nearest surface reaches the camera plane (`depth <= near`).
137
+ * Two callers used `0.1` and the rest `0`, so a camera with no `near` answered two different
138
+ * questions; this is the one value, and it is `0` because the test is about the surface reaching the
139
+ * camera, not the surface being close to it.
140
+ */
141
+ export const LOD_NEAR_PLANE = 0;
142
+
131
143
  /**
132
144
  * The conservative nearest view-space depth of a world-space bounding sphere.
133
145
  *
@@ -146,6 +158,29 @@ export function conservativeViewDepth(
146
158
  return { depth, degenerate: depth <= nearPlane };
147
159
  }
148
160
 
161
+ /**
162
+ * The LOD recipe every caller repeats: the sphere in the camera's view, how far its nearest surface
163
+ * is, and that distance biased for the level table.
164
+ *
165
+ * `depth` is the raw conservative view depth, which a reporter projects an error from; `biased` is
166
+ * the same distance with {@link biasedLodDistance} applied, which a level selection compares. The
167
+ * two are returned together because the six callers each want one of them and each used to spell the
168
+ * step itself — one of them with a near plane of its own.
169
+ */
170
+ export function selectLodFor(
171
+ camera: Camera,
172
+ sphere: Sphere,
173
+ nearPlane: number,
174
+ ): { readonly depth: number; readonly degenerate: boolean; readonly biased: number } {
175
+ const { depth, degenerate } = conservativeViewDepth(
176
+ camera,
177
+ sphere.center,
178
+ sphere.radius,
179
+ nearPlane,
180
+ );
181
+ return { biased: biasedLodDistance(depth), degenerate, depth };
182
+ }
183
+
149
184
  /** The world-space bounding sphere of a cached local sphere under a node's world matrix. */
150
185
  export function worldSphere(
151
186
  local: Sphere,
@@ -232,6 +267,7 @@ interface IParserLike {
232
267
  animations?: { channels?: { target?: { node?: number } }[] }[];
233
268
  extensions?: Record<string, unknown>;
234
269
  meshes?: { name?: string; primitives?: { extensions?: Record<string, unknown> }[] }[];
270
+ nodes?: { mesh?: number; extensions?: Record<string, unknown> }[];
235
271
  };
236
272
  }
237
273
 
@@ -312,10 +348,21 @@ export interface ILodChain {
312
348
  readonly sphere: Sphere;
313
349
  }
314
350
 
315
- /** Triangles one level of a chain submits. */
316
- function drawTriangles(geometry: BufferGeometry): number {
317
- const drawn = geometry.index?.count ?? geometry.getAttribute("position")?.count ?? 0;
318
- return Math.floor(drawn / 3);
351
+ const levelTriangles = new WeakMap<BufferGeometry, number>();
352
+
353
+ /**
354
+ * Triangles one level of a chain submits, read once: a level is an index view nothing edits, and on
355
+ * the owned engine each `geometry.index` read is a bridge crossing (Midway's fleet read it 528 times
356
+ * a frame, `TN_BRIDGE_WARNING`).
357
+ */
358
+ export function drawTriangles(geometry: BufferGeometry): number {
359
+ let triangles = levelTriangles.get(geometry);
360
+ if (triangles === undefined) {
361
+ const drawn = geometry.index?.count ?? geometry.getAttribute("position")?.count ?? 0;
362
+ triangles = Math.floor(drawn / 3);
363
+ levelTriangles.set(geometry, triangles);
364
+ }
365
+ return triangles;
319
366
  }
320
367
 
321
368
  /**
@@ -372,16 +419,15 @@ class ModelLod {
372
419
  return;
373
420
  }
374
421
  const world = worldSphere(this.#chain.sphere, this.#mesh, undefined, this.#mesh.matrixWorld);
375
- const { depth, degenerate } = conservativeViewDepth(
422
+ const { biased, degenerate } = selectLodFor(
376
423
  camera,
377
- world.center,
378
- world.radius,
424
+ world,
379
425
  (camera as ILodCameraLike).near ?? 0,
380
426
  );
381
427
  const view: ILodView = {
382
428
  camera,
383
429
  degenerate,
384
- depth: biasedLodDistance(depth),
430
+ depth: biased,
385
431
  viewportHeight,
386
432
  };
387
433
  const index = selectLodLevel(
@@ -409,10 +455,9 @@ class ModelLod {
409
455
  const container = this.#container;
410
456
  if (container === null) return;
411
457
  const world = worldSphere(rung.sphere, container, undefined, container.matrixWorld);
412
- const { depth, degenerate } = conservativeViewDepth(
458
+ const { biased, degenerate } = selectLodFor(
413
459
  camera,
414
- world.center,
415
- world.radius,
460
+ world,
416
461
  (camera as ILodCameraLike).near ?? 0,
417
462
  );
418
463
  const errors = [...this.#chain.errors, rung.error];
@@ -420,7 +465,7 @@ class ModelLod {
420
465
  const view: ILodView = {
421
466
  camera,
422
467
  degenerate,
423
- depth: biasedLodDistance(depth),
468
+ depth: biased,
424
469
  viewportHeight,
425
470
  };
426
471
  const index = selectLodLevel(
@@ -873,7 +918,47 @@ export function registerModelLodController(mesh: Mesh, controller: IModelLodCont
873
918
  function isChained(object: object): boolean {
874
919
  const mesh = object as Partial<Mesh>;
875
920
  const geometry = mesh.geometry;
876
- return mesh.isMesh === true && geometry !== undefined && chains.has(geometry);
921
+ return (
922
+ mesh.isMesh === true &&
923
+ geometry !== undefined &&
924
+ (chains.has(geometry) || streaming.has(geometry))
925
+ );
926
+ }
927
+
928
+ /**
929
+ * Coarse geometries of streamed models (PRD-860) whose full model is still downloading. They are
930
+ * tracked like a chained mesh, so on the frame the full model lands every mesh over them, a game's
931
+ * clones included, picks its chain up.
932
+ */
933
+ const streaming = new WeakSet<BufferGeometry>();
934
+
935
+ /** A coarse companion's geometry, drawn until {@link upgradeStreamedGeometry} gives it the full model. */
936
+ export function markStreamedGeometry(coarse: BufferGeometry): void {
937
+ streaming.add(coarse);
938
+ }
939
+
940
+ /** True while a geometry is a streamed coarse companion the full model has not replaced yet. */
941
+ export function isStreamedGeometry(geometry: BufferGeometry): boolean {
942
+ return streaming.has(geometry);
943
+ }
944
+
945
+ /**
946
+ * The full model landed: the coarse geometry takes the full base's index and attributes in place,
947
+ * so every mesh holding it (a game's clones, a projection mirror) draws the full model with no
948
+ * object swapped under the game, and it adopts the full chain.
949
+ */
950
+ export function upgradeStreamedGeometry(coarse: BufferGeometry, full: BufferGeometry): void {
951
+ const attributes = full.attributes as Record<string, BufferAttribute>;
952
+ for (const name of Object.keys(coarse.attributes))
953
+ if (attributes[name] === undefined) coarse.deleteAttribute(name);
954
+ for (const [name, attribute] of Object.entries(attributes)) coarse.setAttribute(name, attribute);
955
+ coarse.setIndex(full.index);
956
+ coarse.computeBoundingBox();
957
+ coarse.computeBoundingSphere();
958
+ levelTriangles.delete(coarse);
959
+ const registered = chains.get(full);
960
+ if (registered !== undefined) chains.set(coarse, registered);
961
+ streaming.delete(coarse);
877
962
  }
878
963
 
879
964
  /**
@@ -913,6 +998,7 @@ export class DiscreteLodPlugin {
913
998
  readonly name = TN_DISCRETE_LOD;
914
999
  readonly #failClosed: boolean;
915
1000
  #parser: IParserLike | undefined;
1001
+ #associations: IParserLike["associations"] | undefined;
916
1002
  readonly #pending = new Map<Mesh, IPendingLevels>();
917
1003
  readonly #rungs: { readonly def: IJoinedRungDef; readonly prototype: Object3D }[] = [];
918
1004
  /** A temporary holder for far-mesh prototypes, so widening reaches their joined geometry. */
@@ -930,6 +1016,16 @@ export class DiscreteLodPlugin {
930
1016
  this.#parser = parser;
931
1017
  }
932
1018
 
1019
+ async beforeRoot(): Promise<void> {
1020
+ const parser = this.#parser;
1021
+ if (parser === undefined) return;
1022
+ // Each glTF scene prunes parser.associations; retain the complete node map before that.
1023
+ await Promise.all(
1024
+ (parser.json.nodes ?? []).map((_, index) => parser.getDependency("node", index)),
1025
+ );
1026
+ this.#associations = parser.associations;
1027
+ }
1028
+
933
1029
  #invalid(message: string): void {
934
1030
  if (this.#failClosed) throw new Error(message);
935
1031
  console.error(message);
@@ -938,7 +1034,20 @@ export class DiscreteLodPlugin {
938
1034
  async afterRoot(result: { scene?: Object3D }): Promise<void> {
939
1035
  const parser = this.#parser;
940
1036
  if (parser === undefined) return;
941
- for (const [object, association] of parser.associations) {
1037
+ const associations = this.#associations ?? parser.associations;
1038
+ // GLTFLoader's instancing extension replaces the primitive meshes without copying associations.
1039
+ for (const [object, association] of associations) {
1040
+ if (association?.primitives !== undefined) continue;
1041
+ const node = parser.json.nodes?.[association?.nodes ?? -1];
1042
+ if (node?.mesh === undefined || node.extensions?.EXT_mesh_gpu_instancing === undefined)
1043
+ continue;
1044
+ const parts = object instanceof InstancedMesh ? [object] : (object as Object3D).children;
1045
+ for (const [primitives, mesh] of parts.entries()) {
1046
+ if (!(mesh instanceof InstancedMesh)) continue;
1047
+ associations.set(mesh, { ...association, meshes: node.mesh, primitives });
1048
+ }
1049
+ }
1050
+ for (const [object, association] of associations) {
942
1051
  const mesh = object as Mesh;
943
1052
  if (mesh.isMesh !== true) continue;
944
1053
  const { meshes, primitives } = association;
@@ -1001,7 +1110,11 @@ export class DiscreteLodPlugin {
1001
1110
  }
1002
1111
 
1003
1112
  /** Builds the derived geometries against the mesh's final (widened) attributes and registers. */
1004
- attach(_root: Object3D, policy: IModelLodPolicy | undefined): number {
1113
+ attach(
1114
+ _root: Object3D,
1115
+ policy: IModelLodPolicy | undefined,
1116
+ instancedLod?: typeof attachInstancedLod,
1117
+ ): number {
1005
1118
  const applied: IAppliedLod = {
1006
1119
  hysteresis: policy?.hysteresis ?? DISCRETE_LOD_DEFAULT_HYSTERESIS,
1007
1120
  maxPixelError: policy?.maxPixelError ?? DISCRETE_LOD_DEFAULT_ERROR_PIXELS,
@@ -1054,7 +1167,15 @@ export class DiscreteLodPlugin {
1054
1167
  for (const geometry of levels) chains.set(geometry, registered);
1055
1168
  bumpChains();
1056
1169
  preserveChainClones(registered);
1057
- controllers.set(mesh, new ModelLod(mesh, registered.chain, applied));
1170
+ if (mesh instanceof InstancedMesh) {
1171
+ if (instancedLod === undefined)
1172
+ throw new Error(
1173
+ "TN_discrete_lod requires the instanced LOD attachment for InstancedMesh.",
1174
+ );
1175
+ instancedLod(mesh, { autoLod: policy });
1176
+ } else {
1177
+ controllers.set(mesh, new ModelLod(mesh, registered.chain, applied));
1178
+ }
1058
1179
  appliedCount += 1;
1059
1180
  }
1060
1181
  this.#registerJoinedRungs(applied);
@@ -1318,7 +1439,8 @@ export function updateModelLods(
1318
1439
  for (const mesh of tracking.items) {
1319
1440
  const entry = controllerFor(mesh);
1320
1441
  if (entry === undefined) {
1321
- tracking.items.delete(mesh);
1442
+ // A streamed coarse mesh stays tracked until its full model lands and brings the chain.
1443
+ if (!streaming.has(mesh.geometry)) tracking.items.delete(mesh);
1322
1444
  continue;
1323
1445
  }
1324
1446
  entry.update(camera, viewportHeight);