@threenative/core 0.3.11 → 0.3.12

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 (157) hide show
  1. package/capabilities.json +1096 -26
  2. package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
  3. package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-CWuFRT7G.d.ts} +1 -1
  4. package/dist/chunk-2Z44XSI2.js +35 -0
  5. package/dist/chunk-5O73CDMR.js +1849 -0
  6. package/dist/chunk-6KLNISRJ.js +153 -0
  7. package/dist/chunk-7UUT3TY5.js +133 -0
  8. package/dist/chunk-CFGTPFUH.js +231 -0
  9. package/dist/chunk-DBELTTTM.js +615 -0
  10. package/dist/chunk-GMHATRPW.js +7701 -0
  11. package/dist/chunk-GXY7B3JG.js +46 -0
  12. package/dist/chunk-KIRUKTBQ.js +187 -0
  13. package/dist/chunk-N5LRP4BR.js +220 -0
  14. package/dist/chunk-OKXUCASC.js +2238 -0
  15. package/dist/chunk-QWJEMUUT.js +94 -0
  16. package/dist/chunk-VAZM36TV.js +497 -0
  17. package/dist/{game-DzMcitDO.d.ts → game-D7pAzZUY.d.ts} +15 -3
  18. package/dist/hot.d.ts +3 -3
  19. package/dist/hot.js +2 -46
  20. package/dist/index.d.ts +329 -302
  21. package/dist/index.js +10566 -22552
  22. package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-B6BMqS1r.d.ts} +33 -3
  23. package/dist/playtest.d.ts +3 -3
  24. package/dist/playtest.js +24 -75
  25. package/dist/react-css.js +1 -215
  26. package/dist/react.d.ts +2 -2
  27. package/dist/{renderer-rZm0hVqq.d.ts → renderer-DvFVoAgj.d.ts} +13 -4
  28. package/dist/spells/index.d.ts +643 -0
  29. package/dist/spells/index.js +1558 -0
  30. package/dist/spells/ultra/index.d.ts +1600 -0
  31. package/dist/spells/ultra/index.js +6804 -0
  32. package/dist/terrain-jobs-worker.js +1 -123
  33. package/dist/two-sided-foliage-W523J3UM.js +1 -0
  34. package/dist/ui-layer.js +5 -384
  35. package/dist/worker.js +4 -41
  36. package/dist/world.d.ts +725 -259
  37. package/dist/world.js +16714 -18284
  38. package/mcp/animation-server.mjs +1 -1
  39. package/mcp/animation.mjs +2 -3
  40. package/mcp/engine-server.mjs +142 -47
  41. package/mcp/servers.mjs +9 -2
  42. package/mcp/terrain.mjs +8 -0
  43. package/package.json +14 -6
  44. package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
  45. package/patches/three@0.187.0.patch +2004 -407
  46. package/src/assets.ts +9 -2
  47. package/src/card-lod.ts +152 -0
  48. package/src/compressed-texture-preparation.ts +1008 -0
  49. package/src/frame-budget.ts +31 -20
  50. package/src/game-dev-tools.ts +93 -0
  51. package/src/game-frame-loop.ts +995 -0
  52. package/src/game-renderer-metrics.ts +77 -0
  53. package/src/game-startup.ts +1001 -0
  54. package/src/game-validate.ts +70 -0
  55. package/src/game.ts +253 -1935
  56. package/src/index.ts +27 -2
  57. package/src/launch-diagnostics.ts +22 -12
  58. package/src/look/ao-admission.ts +24 -0
  59. package/src/look/filmic-tone-mapping.ts +15 -13
  60. package/src/look/look-diagnostics.ts +3 -3
  61. package/src/look/quality.ts +10 -5
  62. package/src/look/world-environment.ts +76 -9
  63. package/src/loop.ts +29 -0
  64. package/src/model-lod.ts +42 -3
  65. package/src/particle-kinds.ts +515 -0
  66. package/src/picking.ts +17 -3
  67. package/src/playtest.ts +27 -1
  68. package/src/projection-apply.ts +4 -1
  69. package/src/projection-plan.ts +9 -6
  70. package/src/render/mesh-pool.ts +1 -1
  71. package/src/render/resolution-subrect.ts +2 -0
  72. package/src/render/rough-diffuse.ts +46 -12
  73. package/src/render/soft-shadow.ts +27 -12
  74. package/src/render/virtual-shadow-adaptive.ts +55 -0
  75. package/src/render/virtual-shadow-casters.ts +175 -0
  76. package/src/render/virtual-shadow-layers.ts +76 -0
  77. package/src/render/virtual-shadow-level.ts +224 -0
  78. package/src/render/virtual-shadow-markers.ts +193 -0
  79. package/src/render/virtual-shadow-options.ts +370 -0
  80. package/src/render/virtual-shadow-pages.ts +5 -0
  81. package/src/render/virtual-shadow.ts +213 -992
  82. package/src/render/world-impostor-surface.ts +293 -34
  83. package/src/render-pass-budget.ts +34 -7
  84. package/src/renderProjection.ts +22 -0
  85. package/src/renderer.ts +92 -37
  86. package/src/snow-field.ts +1 -1
  87. package/src/spells/cast-pool.ts +361 -0
  88. package/src/spells/index.ts +177 -0
  89. package/src/spells/mechanisms.ts +295 -0
  90. package/src/spells/reaction-field.ts +415 -0
  91. package/src/spells/spell-lights.ts +139 -0
  92. package/src/spells/spell-world.ts +187 -0
  93. package/src/spells/spell.ts +397 -0
  94. package/src/spells/spells.ts +283 -0
  95. package/src/spells/ultra/engine/camera.ts +184 -0
  96. package/src/spells/ultra/engine/quality.ts +96 -0
  97. package/src/spells/ultra/index.ts +52 -0
  98. package/src/spells/ultra/main.ts +305 -0
  99. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  100. package/src/spells/ultra/spells/cast.ts +233 -0
  101. package/src/spells/ultra/spells/fire.ts +1267 -0
  102. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  103. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  104. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  105. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  106. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  107. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  108. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  109. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  110. package/src/spells/ultra/vfx/common.ts +1195 -0
  111. package/src/spells/ultra/vfx/noise.ts +441 -0
  112. package/src/startup-readiness.ts +128 -34
  113. package/src/version.ts +1 -1
  114. package/src/warmup.ts +56 -8
  115. package/src/water-surface.ts +9 -3
  116. package/src/world-bundle-safety.ts +401 -0
  117. package/src/world-cell-batches.ts +1216 -0
  118. package/src/world-cell-chunks.ts +1132 -0
  119. package/src/world-cell-data.ts +995 -0
  120. package/src/world-cell-impostors.ts +1449 -0
  121. package/src/world-cell-lod-bias.ts +151 -0
  122. package/src/world-cell-models.ts +1074 -0
  123. package/src/world-cell-options.ts +189 -0
  124. package/src/world-cell-placements.ts +694 -0
  125. package/src/world-cell-prewarm.ts +557 -0
  126. package/src/world-cell-readiness.ts +357 -0
  127. package/src/world-cell-render-bundles.ts +459 -0
  128. package/src/world-cell-render-gpu-dress.ts +714 -0
  129. package/src/world-cell-render-main-cull.ts +484 -0
  130. package/src/world-cell-render-shadow-claims.ts +198 -0
  131. package/src/world-cell-render-util.ts +246 -0
  132. package/src/world-cell-render.ts +1493 -0
  133. package/src/world-cell-residency.ts +745 -0
  134. package/src/world-cells.ts +1318 -10418
  135. package/src/world-chunk-shadow.ts +308 -0
  136. package/src/world-collar.ts +315 -0
  137. package/src/world-gpu-flags.ts +163 -0
  138. package/src/world-gpu-readback.ts +881 -0
  139. package/src/world-gpu-reference.ts +510 -0
  140. package/src/world-gpu-scene.ts +214 -2264
  141. package/src/world-gpu-shadow.ts +190 -0
  142. package/src/world-gpu-types.ts +381 -0
  143. package/src/world-gpu-validation.ts +518 -0
  144. package/src/world-heightfield.ts +802 -0
  145. package/src/world-load-limiter.ts +106 -0
  146. package/src/world-noise.ts +241 -0
  147. package/src/world-package.ts +42 -0
  148. package/src/world-region.ts +1 -1
  149. package/src/world-terrain-splat.ts +365 -149
  150. package/src/world-tile-budget.ts +256 -0
  151. package/src/world-tile-geometry.ts +469 -0
  152. package/src/world-tile-lod.ts +408 -0
  153. package/src/world-tile-observation.ts +566 -0
  154. package/src/world-tile-stitch.ts +166 -0
  155. package/src/world-tiles.ts +170 -1745
  156. package/src/world-water-bodies.ts +359 -0
  157. package/src/world.ts +35 -741
@@ -27,6 +27,12 @@ const IMAGE_COLD: IStartupImageState = {
27
27
  };
28
28
 
29
29
  export interface IStartupReadinessOptions {
30
+ /**
31
+ * Final render-owned work (such as shadow maps), checked after warm-up for two quiet frames.
32
+ * Settlement still missing after stableWindowMs resolves readiness anyway and sets `timedOut`:
33
+ * a late shadow costs a pop, never a game that does not start.
34
+ */
35
+ readonly settled?: () => boolean;
30
36
  /** Maximum wall-clock time spent waiting for first-use compilation. */
31
37
  readonly compileBudgetMs?: number;
32
38
  /** Maximum measured callback duration for a stable startup frame. */
@@ -70,8 +76,9 @@ export interface IStartupReadinessOptions {
70
76
  * then hit 28 main-thread tasks over 40 ms, the worst 267 ms, dominated by TSL graph `build` and
71
77
  * by the main thread idling on GPU pipeline creation.
72
78
  *
73
- * Rejections are swallowed: a warm-up that fails must cost hitches, never a game that will not
74
- * start.
79
+ * A rejection fails `whenReady()` so the loading layer can report a first-use failure instead
80
+ * of revealing a world whose pipeline creation failed. A warm-up still running after
81
+ * `stableWindowMs` is slow, not failed: the gate moves on to settlement and sets `timedOut`.
75
82
  */
76
83
  readonly afterHolds?: () => Promise<void> | void;
77
84
  }
@@ -126,8 +133,8 @@ export const STARTUP_IMAGE_TIMEOUT_MS = 3_000;
126
133
  /** One registered hold: the game's own launch work, and the bounded wait for it. */
127
134
  interface IHold {
128
135
  readonly label: string;
129
- /** Polled once per rendered frame for a predicate hold; absent for a promise hold. */
130
- readonly ready?: () => boolean;
136
+ /** Polled for a predicate hold; absent for a promise hold or a failed-open predicate. */
137
+ ready?: () => boolean;
131
138
  release?: (expired: boolean) => void;
132
139
  settled: boolean;
133
140
  timer: ReturnType<typeof setTimeout> | undefined;
@@ -145,6 +152,13 @@ export class StartupReadiness {
145
152
  #stableFrameCount = 0;
146
153
  #started = false;
147
154
  #ready = false;
155
+ #failed = false;
156
+ #cancelled = false;
157
+ readonly #settled: (() => boolean) | undefined;
158
+ #quietFrames = 0;
159
+ #finishing = false;
160
+ #afterHoldsDone = false;
161
+ #timedOut: "warmup" | "settlement" | undefined;
148
162
  #frameWindowDone = false;
149
163
  readonly #holds = new Map<string, IHold>();
150
164
  #holdBudgetMs: number;
@@ -156,6 +170,7 @@ export class StartupReadiness {
156
170
  #compileTimer: ReturnType<typeof setTimeout> | undefined;
157
171
  #windowTimer: ReturnType<typeof setTimeout> | undefined;
158
172
  #resolveReady: () => void = () => undefined;
173
+ #rejectReady: (error: Error) => void = () => undefined;
159
174
  #resolveFrameworkReady: () => void = () => undefined;
160
175
  readonly #readyPromise: Promise<void>;
161
176
  readonly #frameworkReadyPromise: Promise<void>;
@@ -182,15 +197,30 @@ export class StartupReadiness {
182
197
  "holdBudgetMs",
183
198
  );
184
199
  this.#afterHolds = options.afterHolds;
200
+ this.#settled = options.settled;
185
201
  this.#imageReady = options.imageReady;
186
- this.#readyPromise = new Promise<void>((resolve) => {
202
+ this.#readyPromise = new Promise<void>((resolve, reject) => {
187
203
  this.#resolveReady = resolve;
204
+ this.#rejectReady = reject;
188
205
  });
189
206
  this.#frameworkReadyPromise = new Promise<void>((resolve) => {
190
207
  this.#resolveFrameworkReady = resolve;
191
208
  });
192
209
  }
193
210
 
211
+ /** Stop observing a discarded launch without publishing readiness or failure. */
212
+ cancel(): void {
213
+ this.#cancelled = true;
214
+ if (this.#compileTimer !== undefined) clearTimeout(this.#compileTimer);
215
+ if (this.#windowTimer !== undefined) clearTimeout(this.#windowTimer);
216
+ this.#compileTimer = undefined;
217
+ this.#windowTimer = undefined;
218
+ for (const hold of this.#holds.values()) {
219
+ if (hold.timer !== undefined) clearTimeout(hold.timer);
220
+ hold.timer = undefined;
221
+ }
222
+ }
223
+
194
224
  whenReady(): Promise<void> {
195
225
  return this.#readyPromise;
196
226
  }
@@ -227,6 +257,11 @@ export class StartupReadiness {
227
257
  return this.#frameWindowDone;
228
258
  }
229
259
 
260
+ /** Which bounded post-hold wait ran out, if any; readiness resolved anyway. */
261
+ get timedOut(): "warmup" | "settlement" | undefined {
262
+ return this.#timedOut;
263
+ }
264
+
230
265
  /** Labels of holds that have not settled yet, in registration order. */
231
266
  get pendingHolds(): readonly string[] {
232
267
  return [...this.#holds.values()].filter((hold) => !hold.settled).map((hold) => hold.label);
@@ -283,6 +318,7 @@ export class StartupReadiness {
283
318
  budgetMs: number = this.#holdBudgetMs,
284
319
  progress?: () => number,
285
320
  ): void {
321
+ if (this.#cancelled) return;
286
322
  if (typeof label !== "string" || label.trim() === "")
287
323
  throw new Error("TN_STARTUP_HOLD_LABEL_INVALID: a hold needs a non-empty label.");
288
324
  if (this.#holds.has(label))
@@ -303,7 +339,7 @@ export class StartupReadiness {
303
339
  };
304
340
  this.#holds.set(label, hold);
305
341
  const release = (expired: boolean): void => {
306
- if (hold.settled) return;
342
+ if (this.#cancelled || hold.settled) return;
307
343
  this.#sampleHold(hold);
308
344
  hold.progress = undefined;
309
345
  hold.settled = true;
@@ -332,6 +368,17 @@ export class StartupReadiness {
332
368
  }
333
369
  }
334
370
 
371
+ #holdReady(hold: IHold): boolean {
372
+ if (hold.expired || hold.ready === undefined) return true;
373
+ try {
374
+ return hold.ready();
375
+ } catch {
376
+ // Like a rejected promise, a failed predicate remains settled on later quiet polls.
377
+ hold.ready = undefined;
378
+ return true;
379
+ }
380
+ }
381
+
335
382
  /**
336
383
  * Predicate holds settle on rendered frames, not simulation steps: a deterministic playtest clock
337
384
  * advances no fixed step while startup is held, so a gate read only in `afterPhysics` waited on
@@ -340,13 +387,7 @@ export class StartupReadiness {
340
387
  #pollHolds(): void {
341
388
  for (const hold of this.#holds.values()) {
342
389
  if (hold.settled || hold.ready === undefined) continue;
343
- let done: boolean;
344
- try {
345
- done = hold.ready();
346
- } catch {
347
- done = true;
348
- }
349
- if (done) hold.release?.(false);
390
+ if (this.#holdReady(hold)) hold.release?.(false);
350
391
  }
351
392
  }
352
393
 
@@ -408,7 +449,7 @@ export class StartupReadiness {
408
449
 
409
450
  /** Begin the one-time first-use gate after the entered scene has been built. */
410
451
  start(compile?: StartupCompile): void {
411
- if (this.#started) return;
452
+ if (this.#cancelled || this.#started) return;
412
453
  this.#started = true;
413
454
  if (compile === undefined) {
414
455
  this.#finishCompile();
@@ -419,7 +460,9 @@ export class StartupReadiness {
419
460
  // Defer the call one microtask so the already-visible loading layer gets a present before a
420
461
  // renderer that performs synchronous first-use work starts compiling.
421
462
  void Promise.resolve()
422
- .then(() => compile())
463
+ .then(() => {
464
+ if (!this.#cancelled) return compile();
465
+ })
423
466
  .then(
424
467
  () => this.#finishCompile(),
425
468
  () => this.#finishCompile(),
@@ -428,11 +471,24 @@ export class StartupReadiness {
428
471
 
429
472
  /** Feed actual callback wall time, not requestAnimationFrame timestamp spacing. */
430
473
  observe(frameMs: number): void {
474
+ if (this.#cancelled || this.#failed) return;
431
475
  if (!this.#ready) {
432
476
  this.#pollHolds();
433
477
  this.#pollImage();
434
478
  }
435
479
  if (!this.#started || this.#ready) return;
480
+ if (this.#afterHoldsDone && this.#settled !== undefined) {
481
+ const quiet =
482
+ this.#settled() &&
483
+ [...this.#holds.values()].every((hold) => hold.settled && this.#holdReady(hold));
484
+ this.#quietFrames = quiet ? this.#quietFrames + 1 : 0;
485
+ if (this.#quietFrames >= 2) {
486
+ if (this.#windowTimer !== undefined) clearTimeout(this.#windowTimer);
487
+ this.#windowTimer = undefined;
488
+ this.#ready = true;
489
+ this.#resolveReady();
490
+ }
491
+ }
436
492
  if (
437
493
  this.#compileSettled &&
438
494
  Number.isFinite(frameMs) &&
@@ -449,7 +505,7 @@ export class StartupReadiness {
449
505
  }
450
506
 
451
507
  #finishCompile(): void {
452
- if (this.#compileSettled) return;
508
+ if (this.#cancelled || this.#compileSettled) return;
453
509
  this.#compileSettled = true;
454
510
  if (this.#compileTimer !== undefined) clearTimeout(this.#compileTimer);
455
511
  this.#compileTimer = undefined;
@@ -463,7 +519,7 @@ export class StartupReadiness {
463
519
 
464
520
  /** The framework's own work is done. Whether the *world* is ready also depends on the holds and the picture. */
465
521
  #finishFrameWindow(): void {
466
- if (this.#frameWindowDone) return;
522
+ if (this.#cancelled || this.#frameWindowDone) return;
467
523
  this.#frameWindowDone = true;
468
524
  if (this.#windowTimer !== undefined) clearTimeout(this.#windowTimer);
469
525
  this.#windowTimer = undefined;
@@ -473,7 +529,7 @@ export class StartupReadiness {
473
529
  }
474
530
 
475
531
  #resolveIfComplete(): void {
476
- if (this.#ready || !this.#frameWindowDone) return;
532
+ if (this.#cancelled || this.#ready || this.#finishing || !this.#frameWindowDone) return;
477
533
  for (const hold of this.#holds.values()) if (!hold.settled) return;
478
534
  // Last, because it is the only wait that is not the caller's: a renderer that has not drawn a world a
479
535
  // player may see yet keeps the cover, whatever the timers say — and no longer than its own deadline.
@@ -483,26 +539,64 @@ export class StartupReadiness {
483
539
  this.#armImageDeadline();
484
540
  return;
485
541
  }
486
- // Claim readiness before awaiting, so a hold that settles during `afterHolds` cannot re-enter
487
- // and run it twice.
488
- this.#ready = true;
489
- if (this.#imageTimer !== undefined) clearTimeout(this.#imageTimer);
490
- this.#imageTimer = undefined;
542
+ this.#finishing = true;
543
+ const finish = (): void => {
544
+ if (this.#cancelled || this.#failed || this.#afterHoldsDone) return;
545
+ this.#afterHoldsDone = true;
546
+ // `#finishing` claims the reveal before awaiting, so a hold that settles during `afterHolds`
547
+ // cannot re-enter; the image deadline is spent the moment the reveal is decided.
548
+ if (this.#imageTimer !== undefined) clearTimeout(this.#imageTimer);
549
+ this.#imageTimer = undefined;
550
+ if (this.#settled === undefined) {
551
+ this.#ready = true;
552
+ this.#resolveReady();
553
+ } else {
554
+ // Bounded by the frame-window budget. A slow machine gets the world with a late shadow,
555
+ // and `timedOut` says so, instead of a loading screen that never lifts.
556
+ this.#windowTimer = setTimeout(() => {
557
+ this.#windowTimer = undefined;
558
+ if (this.#cancelled || this.#failed || this.#ready) return;
559
+ this.#timedOut ??= "settlement";
560
+ this.#ready = true;
561
+ this.#resolveReady();
562
+ }, this.#stableWindowMs);
563
+ }
564
+ };
491
565
  const afterHolds = this.#afterHolds;
492
- // No holds means no second tier, which means the framework's own pass already saw the whole
493
- // scene. Resolving synchronously there keeps every game that does not stream exactly as it was.
494
566
  if (afterHolds === undefined || this.#holds.size === 0) {
495
- this.#resolveReady();
567
+ finish();
496
568
  return;
497
569
  }
498
- void (async () => {
499
- try {
500
- await afterHolds();
501
- } catch {
502
- // Swallowed on purpose: a warm-up that fails costs hitches, not a game that never starts.
503
- }
504
- this.#resolveReady();
505
- })();
570
+ this.#windowTimer = setTimeout(() => {
571
+ this.#windowTimer = undefined;
572
+ if (this.#cancelled || this.#failed || this.#ready) return;
573
+ // A slow warm-up costs first-use hitches, never a game that does not start.
574
+ this.#timedOut = "warmup";
575
+ finish();
576
+ }, this.#stableWindowMs);
577
+ let afterHoldsWork: Promise<void> | void;
578
+ try {
579
+ afterHoldsWork = afterHolds();
580
+ } catch (error) {
581
+ afterHoldsWork = Promise.reject(error);
582
+ }
583
+ void Promise.resolve(afterHoldsWork).then(
584
+ () => {
585
+ if (this.#afterHoldsDone) return;
586
+ if (this.#windowTimer !== undefined) clearTimeout(this.#windowTimer);
587
+ this.#windowTimer = undefined;
588
+ finish();
589
+ },
590
+ (error: unknown) => {
591
+ // A failure after the warm-up already timed out arrives too late to hold the reveal.
592
+ if (this.#afterHoldsDone) return;
593
+ if (this.#windowTimer !== undefined) clearTimeout(this.#windowTimer);
594
+ this.#windowTimer = undefined;
595
+ if (this.#cancelled || this.#failed || this.#ready) return;
596
+ this.#failed = true;
597
+ this.#rejectReady(error instanceof Error ? error : new Error(String(error)));
598
+ },
599
+ );
506
600
  }
507
601
  }
508
602
 
package/src/version.ts CHANGED
@@ -1,2 +1,2 @@
1
1
  // Generated by scripts/generate-version.mjs - do not edit. Source: package.json.
2
- export const CORE_VERSION = "0.3.11";
2
+ export const CORE_VERSION = "0.3.12";
package/src/warmup.ts CHANGED
@@ -233,6 +233,19 @@ export interface IWarmUpReport {
233
233
  readonly visibilityForced?: number;
234
234
  }
235
235
 
236
+ const warmUpCompletions = new WeakMap<IWarmUpReport, Promise<void>>();
237
+
238
+ /** Internal launch-gate result. The live compiler promise stays out of the serializable report. */
239
+ export async function warmUpSceneWithCompletion(
240
+ renderer: IWarmUpRenderer,
241
+ scene: Object3D,
242
+ camera: Camera,
243
+ options: IWarmUpOptions = {},
244
+ ): Promise<{ readonly report: IWarmUpReport; readonly completion: Promise<void> }> {
245
+ const report = await warmUpScene(renderer, scene, camera, options);
246
+ return { report, completion: warmUpCompletions.get(report) ?? Promise.resolve() };
247
+ }
248
+
236
249
  /** The narrow slice of the renderer this needs. Structural so a test needs no renderer. */
237
250
  export interface IWarmUpRenderer {
238
251
  compileAsync?: (scene: Object3D, camera: Camera, targetScene?: Object3D) => Promise<void>;
@@ -814,24 +827,31 @@ interface IReflectorNodeLike {
814
827
  *
815
828
  * Three's `reflector()` hangs a `_reflectorBaseNode` off a `ReflectorNode` that a material's
816
829
  * `colorNode` (or a node composed around it) references. The walk is bounded and only descends
817
- * real nodes, so a material with no reflector costs one shallow pass.
830
+ * real nodes, so a material with no reflector costs one shallow pass. `seen` holds the shallowest
831
+ * depth each node was reached at: a TSL graph shares subgraphs, and without it every path to a
832
+ * shared node walks it again.
818
833
  */
819
- function nodeHasReflector(root: unknown, depth: number): boolean {
834
+ function nodeHasReflector(root: unknown, depth: number, seen: WeakMap<object, number>): boolean {
820
835
  if (depth > 64 || typeof root !== "object" || root === null) return false;
821
836
  const node = root as IReflectorNodeLike;
822
837
  if (node._reflectorBaseNode !== undefined) return true;
823
838
  if (node.isNode !== true || typeof node.getChildren !== "function") return false;
839
+ const reached = seen.get(root);
840
+ if (reached !== undefined && reached <= depth) return false;
841
+ seen.set(root, depth);
824
842
  try {
825
843
  for (const child of node.getChildren()) {
826
- if (nodeHasReflector(child, depth + 1)) return true;
844
+ if (nodeHasReflector(child, depth + 1, seen)) return true;
827
845
  }
828
846
  } catch {
847
+ seen.delete(root);
829
848
  return false;
830
849
  }
831
850
  return false;
832
851
  }
833
852
 
834
853
  function hasReflector(scene: Object3D): boolean {
854
+ const seen = new WeakMap<object, number>();
835
855
  const stack: Object3D[] = [scene];
836
856
  // A material is read once however many objects draw with it: on the engine, every field of its
837
857
  // values is a call into the host.
@@ -847,7 +867,7 @@ function hasReflector(scene: Object3D): boolean {
847
867
  ) {
848
868
  read.add(material);
849
869
  for (const value of Object.values(material as Record<string, unknown>)) {
850
- if (nodeHasReflector(value, 0)) return true;
870
+ if (nodeHasReflector(value, 0, seen)) return true;
851
871
  }
852
872
  }
853
873
  const children = object.children ?? [];
@@ -1170,6 +1190,7 @@ export async function warmUpScene(
1170
1190
  }
1171
1191
  const compileAsync = renderer.compileAsync.bind(renderer);
1172
1192
  let attempted = 0;
1193
+ const pendingCompiles: Promise<void>[] = [];
1173
1194
  const invokeCompile = (object: Object3D, targetScene?: Object3D): Promise<void> => {
1174
1195
  const compileDeadline =
1175
1196
  (options.granularity ?? "scene") === "scene"
@@ -1205,12 +1226,33 @@ export async function warmUpScene(
1205
1226
  .then(async () => {
1206
1227
  const pass = await renderWarmPassesOnce();
1207
1228
  if (pass === undefined) {
1229
+ // Skipped because the budget ran out first: lazy work, like any compile that never
1230
+ // started. Rejecting here failed a held startup whose compile merely ran long.
1231
+ if (passError === undefined && now() >= startedAt + budgetMs) return;
1208
1232
  throw passError ?? new Error("covered world warm render did not settle");
1209
1233
  }
1210
1234
  });
1211
1235
  };
1212
1236
 
1213
1237
  let gpuDrainSettled = true;
1238
+ const compileWithinDeadline = async (
1239
+ deadline: number,
1240
+ work: Promise<void>,
1241
+ yieldFrame: () => Promise<void>,
1242
+ now: () => number,
1243
+ ): Promise<boolean> => {
1244
+ // `withinDeadline` answers one `false` both for work the deadline outran and for work that
1245
+ // rejected, and only the first is something a held launch may still wait on: a compile that
1246
+ // already failed belongs to the frame that needs its pipeline, where the error belongs.
1247
+ let settled = false;
1248
+ const track = (): void => {
1249
+ settled = true;
1250
+ };
1251
+ void work.then(track, track);
1252
+ const finished = await withinDeadline(deadline, work, yieldFrame, now);
1253
+ if (!finished && !settled) pendingCompiles.push(work);
1254
+ return finished;
1255
+ };
1214
1256
  const finish = (report: IWarmUpReport): IWarmUpReport => {
1215
1257
  const coveredPassIncomplete =
1216
1258
  renderer.warmUpWorldPass !== undefined && passResult === undefined;
@@ -1239,7 +1281,13 @@ export async function warmUpScene(
1239
1281
  complete && cacheIdentity !== undefined
1240
1282
  ? storeWarmUpCache(cacheIdentity, candidates, computeNodes.length)
1241
1283
  : cacheStatus;
1242
- return reconcileWarmUpObservation({ ...normalized, cache: finalCache });
1284
+ const finishedReport = reconcileWarmUpObservation({ ...normalized, cache: finalCache });
1285
+ if (pendingCompiles.length > 0) {
1286
+ const completion = Promise.all(pendingCompiles).then(() => undefined);
1287
+ void completion.catch(() => undefined);
1288
+ warmUpCompletions.set(finishedReport, completion);
1289
+ }
1290
+ return finishedReport;
1243
1291
  };
1244
1292
 
1245
1293
  // The hidden pass render runs once, after the compile and before the ending census snapshot, so
@@ -1305,7 +1353,7 @@ export async function warmUpScene(
1305
1353
  const deadline = startedAt + budgetMs;
1306
1354
  const finished =
1307
1355
  now() < deadline
1308
- ? await withinDeadline(deadline, invokeSceneCompile(), yieldFrame, now)
1356
+ ? await compileWithinDeadline(deadline, invokeSceneCompile(), yieldFrame, now)
1309
1357
  : false;
1310
1358
  options.onProgress?.({ done: finished ? 1 : 0, total: 1 });
1311
1359
  await renderWarmPassesOnce();
@@ -1328,7 +1376,7 @@ export async function warmUpScene(
1328
1376
  const remaining = Math.max(0, startedAt + budgetMs - now());
1329
1377
  const finished =
1330
1378
  remaining > 0
1331
- ? await withinDeadline(startedAt + budgetMs, invokeSceneCompile(), yieldFrame, now)
1379
+ ? await compileWithinDeadline(startedAt + budgetMs, invokeSceneCompile(), yieldFrame, now)
1332
1380
  : false;
1333
1381
  options.onProgress?.({ done: finished ? 1 : 0, total: 1 });
1334
1382
  await renderWarmPassesOnce();
@@ -1391,7 +1439,7 @@ export async function warmUpScene(
1391
1439
  // identity; this layer must not guess which objects are safe to drop before it observes them.
1392
1440
  //
1393
1441
  // Bounded, because an unbounded await here is what held a real launch open forever.
1394
- const finished = await withinDeadline(
1442
+ const finished = await compileWithinDeadline(
1395
1443
  Math.min(deadline, now() + compileTimeoutMs),
1396
1444
  invokeCompile(renderables[index] as Object3D, options.targetScene ?? scene),
1397
1445
  yieldFrame,
@@ -181,7 +181,9 @@ export class WaterSurface3D {
181
181
  // a replay refreshes only listed draws, so those keep the camera they were recorded with. The
182
182
  // mirror renders outside the record, and the record gets its bundle back. A pass three never
183
183
  // updates (the native engine draws it and records no JS bundle) has no render to guard.
184
- if (pass.updateBeforeType !== "none") {
184
+ // The native engine draws the mirror pass itself and exposes no JS update to wrap.
185
+ const jsPass = pass.updateBeforeType !== "none";
186
+ if (jsPass) {
185
187
  const mirror = pass.updateBefore.bind(pass);
186
188
  pass.updateBefore = (frame: IReflectionFrame): void => {
187
189
  const host = frame.renderer as { _currentRenderBundle?: unknown };
@@ -209,7 +211,11 @@ export class WaterSurface3D {
209
211
  return virtual;
210
212
  };
211
213
  }
212
- if (reflection.layers === undefined) {
214
+ if (!jsPass && (reflection.layers === undefined || refreshInterval > 1))
215
+ console.info(
216
+ `TN_WATER_REFLECTION_NATIVE: ${JSON.stringify({ minSizeFilter: false, refreshInterval: 1, reason: "the engine draws the mirror pass natively" })}`,
217
+ );
218
+ if (jsPass && reflection.layers === undefined) {
213
219
  const minSize = finite("reflection.minSize", reflection.minSize ?? 10);
214
220
  if (minSize <= 0) throw new Error("WaterSurface3D.reflection.minSize must be positive.");
215
221
  const render = pass.updateBefore.bind(pass);
@@ -253,7 +259,7 @@ export class WaterSurface3D {
253
259
  }
254
260
  };
255
261
  }
256
- if (refreshInterval > 1) {
262
+ if (jsPass && refreshInterval > 1) {
257
263
  // Every frame the pass redraws the world into its target and binds the result. The render is
258
264
  // the expensive part; the binding is not. Skipping the whole `updateBefore` on the frames
259
265
  // between leaves the previous frame's texture bound and the render target intact, so the