@threenative/core 0.3.6 → 0.3.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/README.md +3 -5
  2. package/capabilities.json +739 -50
  3. package/dist/{assets-CqvE429w.d.ts → assets-YUbXa3-Y.d.ts} +101 -2
  4. package/dist/{canvas-layer-C1-5CviZ.d.ts → canvas-layer-vCtanIeB.d.ts} +1 -1
  5. package/dist/{game-Jz4Fdoeb.d.ts → game-cb99J-YE.d.ts} +100 -31
  6. package/dist/hot.d.ts +4 -4
  7. package/dist/hot.js +23 -5
  8. package/dist/index.d.ts +1742 -29
  9. package/dist/index.js +22443 -12423
  10. package/dist/{model-lod-BDAUYgsS.d.ts → model-lod-CTpZ6imz.d.ts} +1 -1
  11. package/dist/net.js +39 -12
  12. package/dist/playtest.d.ts +4 -4
  13. package/dist/playtest.js +48 -9
  14. package/dist/react-css.js +23 -0
  15. package/dist/react.d.ts +2 -2
  16. package/dist/{renderer-9yEo9hPa.d.ts → renderer-rZm0hVqq.d.ts} +178 -5
  17. package/dist/ui-layer.d.ts +11 -2
  18. package/dist/ui-layer.js +76 -4
  19. package/dist/worker.d.ts +36 -0
  20. package/dist/worker.js +1088 -0
  21. package/dist/world.d.ts +11 -3
  22. package/dist/world.js +1117 -197
  23. package/mcp/animation-server.mjs +265 -0
  24. package/mcp/animation.mjs +22 -0
  25. package/mcp/call.mjs +105 -0
  26. package/mcp/devtools.mjs +5 -0
  27. package/mcp/engine-server.mjs +713 -37
  28. package/mcp/launch.mjs +3 -2
  29. package/mcp/servers.d.mts +2 -0
  30. package/mcp/servers.mjs +33 -8
  31. package/package.json +12 -8
  32. package/patches/three@0.185.1-prd269-upgrade.patch +308 -0
  33. package/patches/three@0.185.1.patch +481 -272
  34. package/src/animation-packet-state.ts +88 -0
  35. package/src/animation-pose-packet.ts +537 -0
  36. package/src/animation.ts +779 -31
  37. package/src/asset-cache.ts +719 -0
  38. package/src/assets.ts +521 -152
  39. package/src/audio.ts +29 -3
  40. package/src/auto-batch.ts +792 -0
  41. package/src/config.ts +2 -0
  42. package/src/frame-budget.ts +268 -2
  43. package/src/game.ts +525 -105
  44. package/src/grounding.ts +7 -6
  45. package/src/hot.ts +19 -5
  46. package/src/index.ts +381 -6
  47. package/src/input.ts +21 -2
  48. package/src/interpolation.ts +19 -1
  49. package/src/launch-diagnostics.ts +7 -2
  50. package/src/look/ao-multibounce.ts +29 -0
  51. package/src/look/ao-reach.ts +39 -0
  52. package/src/look/auto-exposure.ts +264 -0
  53. package/src/look/default-tone-mapping.ts +44 -0
  54. package/src/look/exposure-graph.ts +208 -0
  55. package/src/look/exposure-readback.ts +97 -0
  56. package/src/look/exposure-settings.ts +132 -0
  57. package/src/look/filmic-tone-mapping.ts +852 -0
  58. package/src/look/gi-registry.ts +55 -0
  59. package/src/look/local-exposure.ts +507 -0
  60. package/src/look/look-diagnostics.ts +24 -0
  61. package/src/look/motion-blur.ts +42 -0
  62. package/src/look/quality.ts +309 -0
  63. package/src/look/reflection-trace.ts +344 -0
  64. package/src/look/unreal-bloom.ts +295 -0
  65. package/src/look/vignette.ts +14 -0
  66. package/src/look/world-environment.ts +2033 -0
  67. package/src/loop.ts +25 -1
  68. package/src/merge-parts.ts +25 -10
  69. package/src/model-lod.ts +14 -0
  70. package/src/net-session.ts +58 -14
  71. package/src/ocean/spectral.ts +41 -7
  72. package/src/picking.ts +72 -5
  73. package/src/platform.ts +29 -1
  74. package/src/playtest.ts +54 -8
  75. package/src/profiling/FrameCounters.ts +166 -5
  76. package/src/profiling/FrameStages.ts +289 -0
  77. package/src/profiling/Spans.ts +39 -25
  78. package/src/profiling/debug-telemetry.ts +312 -0
  79. package/src/profiling/scene-warning.ts +42 -6
  80. package/src/projection-apply.ts +11 -3
  81. package/src/projection-content.ts +189 -0
  82. package/src/projection-marker.ts +6 -2
  83. package/src/projection-plan.ts +279 -28
  84. package/src/projection-skinned.ts +620 -5
  85. package/src/projection-stability.ts +16 -0
  86. package/src/projection-uniform.ts +5 -1
  87. package/src/quiet-markers.ts +56 -0
  88. package/src/render/budget-ladder.ts +256 -0
  89. package/src/render/chain.ts +89 -7
  90. package/src/render/exposure-units.ts +59 -0
  91. package/src/render/frame-time-budget.ts +162 -0
  92. package/src/render/gi-budget.ts +231 -0
  93. package/src/render/gi-visualize.ts +49 -0
  94. package/src/render/material-key.ts +1 -0
  95. package/src/render/probe-volume.ts +196 -36
  96. package/src/render/rough-diffuse.ts +177 -0
  97. package/src/render/scene-trace.ts +532 -0
  98. package/src/render/shadow-filter-budget.ts +237 -0
  99. package/src/render/sky-capture.ts +194 -0
  100. package/src/render/soft-shadow.ts +607 -0
  101. package/src/render/surface-cache.ts +418 -0
  102. package/src/render/traced-reflections.ts +408 -0
  103. package/src/render/two-sided-foliage.ts +120 -0
  104. package/src/render/virtual-shadow-pages.ts +112 -12
  105. package/src/render/virtual-shadow.ts +386 -38
  106. package/src/render-camera-cull.ts +536 -31
  107. package/src/render-pass-budget.ts +140 -22
  108. package/src/renderProjection.ts +65 -9
  109. package/src/renderer-config.ts +3 -2
  110. package/src/renderer.ts +289 -14
  111. package/src/resolution-scaler.ts +65 -7
  112. package/src/skeletal-mesh.ts +4 -0
  113. package/src/snow-field.ts +46 -0
  114. package/src/softbody.ts +6 -5
  115. package/src/startup-offscreen-bytes.ts +168 -0
  116. package/src/startup-readiness.ts +137 -2
  117. package/src/ui-bridge.ts +38 -0
  118. package/src/ui-hit-regions.ts +6 -2
  119. package/src/ui-layer.ts +1 -0
  120. package/src/ui-state.ts +32 -3
  121. package/src/version.ts +1 -1
  122. package/src/viewport.ts +8 -5
  123. package/src/warmup.ts +76 -10
  124. package/src/worker-audio.ts +579 -0
  125. package/src/worker.ts +842 -0
  126. package/src/world-cells.ts +4 -1
  127. package/gpl/LICENSE.GPL +0 -117
  128. package/gpl/convert.py +0 -192
  129. package/gpl/fixtures/make_world_fixture.py +0 -184
  130. package/gpl/recipes/_common.py +0 -180
  131. package/gpl/recipes/bake_ao.py +0 -111
  132. package/gpl/recipes/decimate.py +0 -70
  133. package/gpl/recipes/export_world.py +0 -699
  134. package/gpl/recipes/retarget.py +0 -131
  135. package/gpl/recipes/unwrap.py +0 -71
  136. package/mcp/blender-server.mjs +0 -689
  137. package/mcp/blender.mjs +0 -26
@@ -106,6 +106,23 @@ interface IRenderCounters {
106
106
  * cannot read a `userData` off is left unattributed rather than guessed at.
107
107
  */
108
108
  interface IInfoCounters {
109
+ /**
110
+ * The owned (Wasm) engine draws its shadow passes inside its one render call, so `info.render` adds them to the
111
+ * main camera's. It reports the two apart here, and the recorder files them as `main` and `shadow`, as three's nested
112
+ * shadow renders are.
113
+ */
114
+ readonly engine?:
115
+ | {
116
+ readonly frameSplit?:
117
+ | {
118
+ readonly mainDraws: number;
119
+ readonly mainTriangles: number;
120
+ readonly shadowDraws: number;
121
+ readonly shadowTriangles: number;
122
+ }
123
+ | undefined;
124
+ }
125
+ | undefined;
109
126
  readonly render?: IRenderCounters | undefined;
110
127
  update?(object: unknown, count: number, instanceCount: number): void;
111
128
  }
@@ -145,6 +162,8 @@ export interface IRenderPassTarget {
145
162
  /** One allocated timestamp query, before its duration resolves: the pass kind and three's uid. */
146
163
  interface IGpuUidEntry {
147
164
  readonly kind: FramePassKind;
165
+ /** The scene name three gave the render call, `""` for a call that had none. */
166
+ readonly name: string;
148
167
  readonly uid: string;
149
168
  }
150
169
 
@@ -182,6 +201,7 @@ interface IPassFrame {
182
201
  readonly entryDraws: number;
183
202
  readonly entryTriangles: number;
184
203
  readonly kind: FramePassKind;
204
+ readonly name: string;
185
205
  childDraws: number;
186
206
  childTriangles: number;
187
207
  /** Timestamp uids the nested calls this pass made allocated, in allocation order. */
@@ -213,20 +233,39 @@ const installed = new WeakSet<object>();
213
233
  const GPU_UID_FRAME_LIMIT = 64;
214
234
 
215
235
  /**
216
- * Names a render call by what three already calls it: the outermost call is the main camera, and a
236
+ * Names a render call by what three already calls it: the first camera call is the main pass, and a
217
237
  * nested call carries the scene name three or the reflector gave it.
238
+ *
239
+ * The name is read before the depth because a post pipeline makes its shadow or reflection passes at
240
+ * world depth 0 — the composite quad is not a world call, so it does not hold one.
218
241
  */
219
- function passKind(scene: unknown, depth: number): FramePassKind {
220
- if (depth === 0) return "main";
221
- const name =
242
+ function passKind(name: string, depth: number): FramePassKind {
243
+ if (name.startsWith("Shadow Map")) return "shadow";
244
+ if (/reflect/iu.test(name)) return "reflection";
245
+ return depth === 0 ? "main" : "nested";
246
+ }
247
+
248
+ /**
249
+ * Whether a render call is three's post-pipeline composite: `RenderPipeline.render()` submits one
250
+ * full-screen quad (`renderer.render(this, _camera)`) and makes the world a nested render from
251
+ * `PassNode`, so a call whose scene three flags `isQuadMesh` is the composite, never a world pass.
252
+ * Three's `QuadMesh` exists only for pipeline output; a scene graph has none.
253
+ */
254
+ function isFullscreenQuad(scene: unknown): boolean {
255
+ return (
222
256
  typeof scene === "object" &&
257
+ scene !== null &&
258
+ (scene as { isQuadMesh?: unknown }).isQuadMesh === true
259
+ );
260
+ }
261
+
262
+ /** The name three or the game gave the scene a render call draws, or `""`. */
263
+ function sceneName(scene: unknown): string {
264
+ return typeof scene === "object" &&
223
265
  scene !== null &&
224
266
  typeof (scene as { name?: unknown }).name === "string"
225
- ? (scene as { name: string }).name
226
- : "";
227
- if (name.startsWith("Shadow Map")) return "shadow";
228
- if (/reflect/iu.test(name)) return "reflection";
229
- return "nested";
267
+ ? (scene as { name: string }).name
268
+ : "";
230
269
  }
231
270
 
232
271
  /**
@@ -253,11 +292,68 @@ export function noteShadowRedrawGpuMs(renderer: object, ms: number): void {
253
292
  lastShadowGpuMs.set(renderer, ms);
254
293
  }
255
294
 
295
+ /**
296
+ * The stage name of the shadow passes' summed GPU time in a stage reading: three's `Shadow Map`
297
+ * passes here, the owned engine's shadow segment there. A frame that drew no shadow pass has none.
298
+ */
299
+ export const SHADOW_STAGE = "Shadow";
300
+
301
+ /**
302
+ * One resolved frame's GPU milliseconds by stage: `stages` sums the nested passes that carry the same
303
+ * scene name (three names its post passes `SSGI` and `AO`), and `total` is the whole frame.
304
+ */
305
+ export interface IStageGpuReading {
306
+ readonly frame: number;
307
+ readonly stages: Readonly<Record<string, number>>;
308
+ readonly total: number;
309
+ }
310
+
311
+ /** The last whole frame's stage readings per instrumented renderer; see {@link stageGpuReading}. */
312
+ const lastStageGpu = new WeakMap<object, IStageGpuReading>();
313
+
314
+ /**
315
+ * The newest whole frame's GPU milliseconds by named stage on this renderer, or `undefined` before
316
+ * one resolved (or with neither a recorder installed nor an owned engine, or an adapter that grants
317
+ * no timestamp query). The `frame` number lets a reader count each resolved frame once. A stage that
318
+ * did not draw is absent.
319
+ */
320
+ export function stageGpuReading(renderer: unknown): IStageGpuReading | undefined {
321
+ if (typeof renderer !== "object" || renderer === null) return undefined;
322
+ return lastStageGpu.get(renderer) ?? ownedEngineReading(renderer);
323
+ }
324
+
325
+ interface IOwnedEngineRenderer {
326
+ readonly backend?: { getTimestampFrames?(type: string): readonly number[] };
327
+ readonly info?: {
328
+ readonly engine?: { readonly gpuStages?: Readonly<Record<string, number>> };
329
+ readonly render?: { readonly timestamp?: number };
330
+ };
331
+ }
332
+
333
+ /**
334
+ * The owned (Wasm) engine times its passes natively and has no timestamp pool for the recorder to
335
+ * read: it reports its newest sample itself, the whole frame as `info.render.timestamp`, the stages
336
+ * its passes are labelled with as `info.engine.gpuStages`, and the frame they belong to as the last
337
+ * `getTimestampFrames("render")` entry (three-native `browser-renderer.ts`). Three's renderer has
338
+ * none of `gpuStages`, so it falls through to `undefined`.
339
+ */
340
+ function ownedEngineReading(renderer: IOwnedEngineRenderer): IStageGpuReading | undefined {
341
+ const frames = renderer.backend?.getTimestampFrames?.("render");
342
+ const frame = frames?.[frames.length - 1];
343
+ const stages = renderer.info?.engine?.gpuStages;
344
+ const total = renderer.info?.render?.timestamp;
345
+ if (frame === undefined || stages === undefined || typeof total !== "number" || !(total > 0))
346
+ return undefined;
347
+ return { frame, stages, total };
348
+ }
349
+
256
350
  export class RenderPassBudget {
257
351
  readonly #target: IRenderPassTarget;
258
352
  readonly #original: (scene: unknown, camera: unknown) => void;
259
353
  readonly #frame: IRenderPassSample[] = [];
260
354
  readonly #stack: IPassFrame[] = [];
355
+ /** How many non-quad render calls are open: the depth the camera pass is classified at. */
356
+ #worldDepth = 0;
261
357
  /** Timestamp uids each render call allocated, keyed by the Three.js frame they belong to. */
262
358
  readonly #gpuUids = new Map<number, IGpuUidEntry[]>();
263
359
  /** The last frame `nextGpuFrame` handed out; every earlier frame has been reported. */
@@ -274,18 +370,22 @@ export class RenderPassBudget {
274
370
  }
275
371
  const offsets = target.backend?.timestampQueryPool?.render?.queryOffsets;
276
372
  const allocatedBefore = offsets?.size ?? 0;
277
- const depth = this.#stack.length;
373
+ const name = sceneName(scene);
374
+ const quad = isFullscreenQuad(scene);
278
375
  const frame: IPassFrame = {
279
376
  childDraws: 0,
280
377
  childTriangles: 0,
281
378
  entryDraws: counters.draws,
282
379
  entryTriangles: counters.triangles,
283
- kind: passKind(scene, depth),
380
+ kind: quad ? "nested" : passKind(name, this.#worldDepth),
381
+ name,
284
382
  };
285
383
  this.#stack.push(frame);
384
+ if (!quad) this.#worldDepth += 1;
286
385
  try {
287
386
  this.#original.call(target, scene, camera);
288
387
  } finally {
388
+ if (!quad) this.#worldDepth -= 1;
289
389
  this.#stack.pop();
290
390
  const after = readCounters(target);
291
391
  if (after !== undefined) {
@@ -297,12 +397,19 @@ export class RenderPassBudget {
297
397
  parent.childTriangles += totalTriangles;
298
398
  }
299
399
  const drawsBySource = frame.unclassifiable === true ? undefined : frame.drawsBySource;
400
+ const split = frame.kind === "main" ? target.info?.engine?.frameSplit : undefined;
300
401
  this.#frame.push({
301
- draws: Math.max(0, totalDraws - frame.childDraws),
402
+ draws: split?.mainDraws ?? Math.max(0, totalDraws - frame.childDraws),
302
403
  ...(drawsBySource === undefined ? {} : { drawsBySource }),
303
404
  kind: frame.kind,
304
- triangles: Math.max(0, totalTriangles - frame.childTriangles),
405
+ triangles: split?.mainTriangles ?? Math.max(0, totalTriangles - frame.childTriangles),
305
406
  });
407
+ if (split !== undefined && split.shadowDraws > 0)
408
+ this.#frame.push({
409
+ draws: split.shadowDraws,
410
+ kind: "shadow",
411
+ triangles: split.shadowTriangles,
412
+ });
306
413
  }
307
414
  this.#attributeGpu(frame, offsets, allocatedBefore);
308
415
  }
@@ -412,6 +519,9 @@ export class RenderPassBudget {
412
519
  if (sum === undefined) continue;
413
520
  this.#deliveredGpuFrame = frame;
414
521
  if (sum.shadowPasses > 0) noteShadowRedrawGpuMs(this.#target, sum.shadow);
522
+ const stages =
523
+ sum.shadowPasses > 0 ? { ...sum.stages, [SHADOW_STAGE]: sum.shadow } : sum.stages;
524
+ lastStageGpu.set(this.#target, { frame, stages, total: sum.total });
415
525
  return {
416
526
  frame,
417
527
  main: sum.main,
@@ -429,9 +539,15 @@ export class RenderPassBudget {
429
539
  * everything else — so the frame's own cost does not have to be inferred from three's one number
430
540
  * for the batch, and it is only ever returned whole.
431
541
  */
432
- #gpuSum(
433
- frame: number,
434
- ): { main: number; shadow: number; shadowPasses: number; total: number } | undefined {
542
+ #gpuSum(frame: number):
543
+ | {
544
+ main: number;
545
+ shadow: number;
546
+ shadowPasses: number;
547
+ stages: Record<string, number>;
548
+ total: number;
549
+ }
550
+ | undefined {
435
551
  const entries = this.#gpuUids.get(frame);
436
552
  const timestamps = this.#target.backend?.timestampQueryPool?.render?.timestamps;
437
553
  if (timestamps === undefined || entries === undefined || entries.length === 0) return undefined;
@@ -440,7 +556,8 @@ export class RenderPassBudget {
440
556
  let shadowPasses = 0;
441
557
  let total = 0;
442
558
  let resolved = 0;
443
- for (const { kind, uid } of entries) {
559
+ const stages: Record<string, number> = {};
560
+ for (const { kind, name, uid } of entries) {
444
561
  if (kind === "shadow") shadowPasses += 1;
445
562
  const ms = timestamps.get(uid);
446
563
  if (ms === undefined || !Number.isFinite(ms) || ms < 0) continue;
@@ -448,11 +565,12 @@ export class RenderPassBudget {
448
565
  total += ms;
449
566
  if (kind === "main") main += ms;
450
567
  else if (kind === "shadow") shadow += ms;
568
+ else if (kind === "nested" && name !== "") stages[name] = (stages[name] ?? 0) + ms;
451
569
  }
452
570
  // A partial sum is not the frame's cost: subtracting the known kinds from a partial `total`
453
571
  // leaves an `other` no one measured. The frame stays absent until the whole read is in.
454
572
  if (resolved !== entries.length) return undefined;
455
- return { main, shadow, shadowPasses, total };
573
+ return { main, shadow, shadowPasses, stages, total };
456
574
  }
457
575
 
458
576
  /**
@@ -481,17 +599,17 @@ export class RenderPassBudget {
481
599
  parent.childUids ??= [];
482
600
  parent.childUids.push(...allocated);
483
601
  }
484
- for (const uid of own) this.#recordGpuUid(uid, frame.kind);
602
+ for (const uid of own) this.#recordGpuUid(uid, frame.kind, frame.name);
485
603
  }
486
604
 
487
605
  /** Files one allocated uid under the frame the uid names, dropping the oldest frames over time. */
488
- #recordGpuUid(uid: string, kind: FramePassKind): void {
606
+ #recordGpuUid(uid: string, kind: FramePassKind, name: string): void {
489
607
  const match = /:f(\d+)$/u.exec(uid);
490
608
  if (match === null) return;
491
609
  const frame = Number(match[1]);
492
610
  const entries = this.#gpuUids.get(frame);
493
- if (entries === undefined) this.#gpuUids.set(frame, [{ kind, uid }]);
494
- else entries.push({ kind, uid });
611
+ if (entries === undefined) this.#gpuUids.set(frame, [{ kind, name, uid }]);
612
+ else entries.push({ kind, name, uid });
495
613
  while (this.#gpuUids.size > GPU_UID_FRAME_LIMIT) {
496
614
  const oldest = this.#gpuUids.keys().next().value;
497
615
  if (oldest === undefined) break;
@@ -4,7 +4,9 @@ import type { IGeometryOwnership } from "./geometry-capture.js";
4
4
  import type { MatrixWorldPass } from "./matrix-world.js";
5
5
  import { ProjectionMirror } from "./projection-apply.js";
6
6
  import {
7
+ type IProjectionDeclineCount,
7
8
  type IProjectionProjectPlan,
9
+ type ProjectionDeclineCauseCode,
8
10
  createProjectionScanWorkspace,
9
11
  isRenderable,
10
12
  releaseProjectionScanWorkspace,
@@ -95,12 +97,38 @@ export type ProjectionExactReason =
95
97
  */
96
98
  export type ProjectionMaterialChecks = "spread" | "everyFrame";
97
99
 
100
+ /**
101
+ * Why a `notWorthwhile` scene had too many meshes drawing alone, with the change that fixes it, so an
102
+ * agent reading TN_RENDER_PROJECTION learns what to edit rather than only that batching declined.
103
+ */
104
+ export interface IProjectionDeclineCause extends IProjectionDeclineCount {
105
+ readonly hint: string;
106
+ }
107
+
108
+ const DECLINE_HINTS: Record<ProjectionDeclineCauseCode, string> = {
109
+ uniqueGeometry:
110
+ "meshes whose geometry data differs cannot share a draw; build each model once and clone() it, or reuse one geometry for every copy",
111
+ uniqueMaterial:
112
+ "copies share a shape but not a material; reuse one material per surface (copies may differ only in color) and the same castShadow, receiveShadow and layers",
113
+ };
114
+
115
+ function declineCauseOf(
116
+ count: IProjectionDeclineCount | undefined,
117
+ ): IProjectionDeclineCause | undefined {
118
+ return count === undefined ? undefined : { ...count, hint: DECLINE_HINTS[count.code] };
119
+ }
120
+
121
+ /** What the window line reads: the report less its one scene-walking field. */
122
+ export type ProjectionWindowReport = Omit<IRenderProjectionReport, "resultDrawCandidates">;
123
+
98
124
  export interface IRenderProjectionReport {
99
125
  readonly schemaVersion: 1;
100
126
  /** True while the renderer is being handed the mirror rather than the authored scene. */
101
127
  readonly projecting: boolean;
102
128
  readonly reasonCode: ProjectionReasonCode;
103
129
  readonly reason?: string;
130
+ /** Set on a `notWorthwhile` decline: which meshes drew alone, how many, and what to change. */
131
+ readonly cause?: IProjectionDeclineCause;
104
132
  /** Renderables the authored scene holds — what an unoptimized frame would walk and draw. */
105
133
  readonly sourceRenderables: number;
106
134
  /**
@@ -220,6 +248,9 @@ interface IHostProjectionVerdict {
220
248
  readonly skinnedBatches: number;
221
249
  readonly exactObjects: number;
222
250
  readonly exact: Partial<Record<ProjectionExactReason, number>>;
251
+ /** On a `notWorthwhile` decline: the cause code and its mesh count, as the JS scan names them. */
252
+ readonly cause?: ProjectionDeclineCauseCode;
253
+ readonly causeMeshes?: number;
223
254
  }
224
255
 
225
256
  /**
@@ -283,6 +314,7 @@ export class SceneRenderProjection {
283
314
  #deoptimized = true;
284
315
  #reasonCode: ProjectionReasonCode = "belowMeshFloor";
285
316
  #reason: string | undefined;
317
+ #cause: IProjectionDeclineCause | undefined;
286
318
  #sourceRenderables = 0;
287
319
  #reconcileMs = 0;
288
320
  #lastReconcileMs = 0;
@@ -376,7 +408,7 @@ export class SceneRenderProjection {
376
408
  }
377
409
  const host = this.#host;
378
410
  if (host !== undefined) {
379
- this.#reconcileHost(host, velocityEnabled);
411
+ this.#reconcileHost(host);
380
412
  return;
381
413
  }
382
414
  const mirror = this.#mirror;
@@ -448,7 +480,7 @@ export class SceneRenderProjection {
448
480
  if (scan.plan.action === "decline") {
449
481
  this.#forgetPlan();
450
482
  mirror.releaseAll();
451
- this.#deoptimize(scan.plan.reasonCode, scan.plan.reason);
483
+ this.#deoptimize(scan.plan.reasonCode, scan.plan.reason, scan.plan.cause);
452
484
  // A scene with nothing in it yet is still loading, and walking it costs nothing: look
453
485
  // again next frame rather than drawing the first second of the level unprojected.
454
486
  if (scan.renderables === 0) this.#framesSinceDeclineScan = DECLINE_RESCAN_FRAMES;
@@ -477,6 +509,7 @@ export class SceneRenderProjection {
477
509
  this.#deoptimized = false;
478
510
  this.#reasonCode = "projected";
479
511
  this.#reason = undefined;
512
+ this.#cause = undefined;
480
513
  }
481
514
  }
482
515
 
@@ -493,10 +526,12 @@ export class SceneRenderProjection {
493
526
  * here: one call reports what its batching made of the frame. The world-matrix pass stays the
494
527
  * frame loop's (it runs on the root the renderer is handed, which is this scene).
495
528
  */
496
- #reconcileHost(host: IHostProjectionRoot, velocityEnabled: boolean): void {
529
+ #reconcileHost(host: IHostProjectionRoot): void {
497
530
  const startedAt = globalThis.performance?.now() ?? 0;
498
- if (velocityEnabled) this.#velocityTracker.update(this.#source);
499
- else this.#velocityTracker.clear();
531
+ // The host engine keeps each object's previous transform itself (its temporal pass's
532
+ // `previousModel`) and reads none of this tracker's history; tracking here would only cross
533
+ // the bridge for every matrix twice a frame (about 2 ms a frame on a 400-object scene).
534
+ this.#velocityTracker.clear();
500
535
  const verdict = host.__tnProjectionReport(this.#minMeshes);
501
536
  this.#hostVerdict = verdict;
502
537
  this.#sourceRenderables = verdict.sourceRenderables;
@@ -504,6 +539,10 @@ export class SceneRenderProjection {
504
539
  this.#reason = verdict.projecting
505
540
  ? undefined
506
541
  : `the host renderer declined this scene (${verdict.reasonCode})`;
542
+ this.#cause =
543
+ verdict.cause === undefined || verdict.projecting
544
+ ? undefined
545
+ : declineCauseOf({ code: verdict.cause, meshes: verdict.causeMeshes ?? 0 });
507
546
  this.#recordReconcile(startedAt);
508
547
  this.#publish();
509
548
  }
@@ -568,6 +607,7 @@ export class SceneRenderProjection {
568
607
  projecting: r.projecting,
569
608
  reasonCode: r.reasonCode,
570
609
  ...(r.reason === undefined ? {} : { reason: r.reason }),
610
+ ...(r.cause === undefined ? {} : { cause: r.cause }),
571
611
  sourceRenderables: r.sourceRenderables,
572
612
  resultDrawCandidates: r.resultDrawCandidates,
573
613
  batches: r.batches,
@@ -598,14 +638,24 @@ export class SceneRenderProjection {
598
638
 
599
639
  get report(): IRenderProjectionReport {
600
640
  if (this.#host !== undefined) return this.#hostReport(this.#hostVerdict ?? NO_HOST_VERDICT);
601
- const exact: Partial<Record<ProjectionExactReason, number>> = {};
602
- for (const [reason, count] of this.#mirror?.exactCounts ?? []) exact[reason] = count;
603
641
  let resultDrawCandidates = 0;
604
642
  // Counted from the scene the renderer is actually handed. Anything else is this class marking
605
643
  // its own homework.
606
644
  this.root.traverse((object) => {
607
645
  if (isRenderable(object)) resultDrawCandidates += 1;
608
646
  });
647
+ return { ...this.windowReport, resultDrawCandidates };
648
+ }
649
+
650
+ /**
651
+ * {@link report} less `resultDrawCandidates`, the one field that walks the scene. The window line
652
+ * every five seconds reads this: on the native engine the walk crosses the bridge per node, and
653
+ * the shooter town's 8,900 nodes made that window's frame miss its vsync.
654
+ */
655
+ get windowReport(): ProjectionWindowReport {
656
+ if (this.#host !== undefined) return this.#hostReport(this.#hostVerdict ?? NO_HOST_VERDICT);
657
+ const exact: Partial<Record<ProjectionExactReason, number>> = {};
658
+ for (const [reason, count] of this.#mirror?.exactCounts ?? []) exact[reason] = count;
609
659
  const batches = this.#deoptimized ? 0 : (this.#mirror?.batchCount ?? 0);
610
660
  const exactObjects = this.#deoptimized ? 0 : (this.#mirror?.proxyCount ?? 0);
611
661
  return {
@@ -613,8 +663,8 @@ export class SceneRenderProjection {
613
663
  projecting: !this.#deoptimized,
614
664
  reasonCode: this.#reasonCode,
615
665
  ...(this.#reason === undefined ? {} : { reason: this.#reason }),
666
+ ...(this.#cause === undefined ? {} : { cause: this.#cause }),
616
667
  sourceRenderables: this.#sourceRenderables,
617
- resultDrawCandidates,
618
668
  projectedObjects: this.#deoptimized ? 0 : (this.#mirror?.projectedObjects ?? 0),
619
669
  batches,
620
670
  instancedBatches: this.#deoptimized ? 0 : (this.#mirror?.instancedBatchCount ?? 0),
@@ -659,6 +709,7 @@ export class SceneRenderProjection {
659
709
  projecting,
660
710
  reasonCode: this.#reasonCode,
661
711
  ...(this.#reason === undefined ? {} : { reason: this.#reason }),
712
+ ...(this.#cause === undefined ? {} : { cause: this.#cause }),
662
713
  sourceRenderables: verdict.sourceRenderables,
663
714
  resultDrawCandidates: verdict.sourceRenderables,
664
715
  projectedObjects: projecting ? verdict.projectedObjects : 0,
@@ -705,10 +756,15 @@ export class SceneRenderProjection {
705
756
  }
706
757
 
707
758
  /** Hands this frame back to the authored scene, naming why. */
708
- #deoptimize(reasonCode: ProjectionReasonCode, reason: string): void {
759
+ #deoptimize(
760
+ reasonCode: ProjectionReasonCode,
761
+ reason: string,
762
+ cause?: IProjectionDeclineCount,
763
+ ): void {
709
764
  this.#deoptimized = true;
710
765
  this.#reasonCode = reasonCode;
711
766
  this.#reason = reason;
767
+ this.#cause = declineCauseOf(cause);
712
768
  }
713
769
 
714
770
  /**
@@ -65,8 +65,9 @@ export function resolveRendererScaleSetting(
65
65
  *
66
66
  * Android and iOS keep every rung: those rungs are what the device arm measured, and a phone buys
67
67
  * the pixels back in ways a desktop does not. Everything else stops at
68
- * `RESOLUTION_SCALER.desktopFloorScale`, because a desktop with nothing reconstructing the frame
69
- * from fewer pixels turns the bottom of that ladder into blocky mush rather than a faster frame.
68
+ * `RESOLUTION_SCALER.desktopFloorScale` (full resolution), because a desktop with nothing
69
+ * reconstructing the frame from fewer pixels shows every lost rung as blur, as Unreal's default
70
+ * of no dynamic resolution without its temporal upscaler assumes.
70
71
  * A desktop whose render chain does reconstruct it lifts the floor itself, per step.
71
72
  */
72
73
  export function resolvePlatformResolutionFloor(os: PlatformOS): number | undefined {