@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
package/src/renderer.ts CHANGED
@@ -22,11 +22,14 @@ import {
22
22
  type IGpuFrameObservation,
23
23
  type IGpuFrameObservationOptions,
24
24
  } from "./gpu-frame-observation.js";
25
+ import { type RendererToneMapping, applyRendererToneMapping } from "./look/default-tone-mapping.js";
26
+ import { qualityTiers } from "./look/quality.js";
25
27
  import {
26
28
  type IPipelineCensus,
27
29
  type PipelineCensus,
28
30
  createPipelineCensus,
29
31
  } from "./pipeline-census.js";
32
+ import { hostDocument, hostResizeObserver } from "./platform.js";
30
33
  import type { ITimestampQueryPool } from "./render-pass-budget.js";
31
34
  import { AlphaAntialiasing, type IAlphaAntialiasingReport } from "./render/alpha-antialiasing.js";
32
35
  import {
@@ -36,6 +39,7 @@ import {
36
39
  } from "./render/chain.js";
37
40
  import { type IResolutionSubrect, ResolutionSubrect } from "./render/resolution-subrect.js";
38
41
 
42
+ import type { IStartupImageState } from "./startup-readiness.js";
39
43
  import {
40
44
  type IStorageBufferLease,
41
45
  type IStorageBufferSource,
@@ -180,8 +184,29 @@ export interface IRendererLike {
180
184
  warmUpSettled?(): void;
181
185
  /** Marks a repeatable streamed warm-up boundary for the next first draw. */
182
186
  warmUpScopeSettled?(label: string, target?: Object3D): void;
183
- /** Performs one covered output-pipeline render without marking first present. */
184
- warmUpWorldPass?(scene: Object3D, camera: Camera, targetScene?: Object3D): void;
187
+ /**
188
+ * Holds the native canvas at its last picture while the startup's first world frame is still cold: every frame
189
+ * still draws, but takes no surface texture, so a world whose shadow and exposure inputs are not ready never
190
+ * reaches the display. Present only on the Wasm engine; a renderer without it draws and presents as before.
191
+ */
192
+ setPresentationHeld?(held: boolean): void;
193
+ /**
194
+ * A held startup's first world frame: `ready` once an ordinary submission drew since the hold engaged, that
195
+ * frame's shadow inputs are initialized, and this install's auto exposure measured within 3% of its target; the
196
+ * two inputs say which one is still cold, so a launch that revealed at its deadline names what never arrived.
197
+ * Absent wherever the hold is.
198
+ */
199
+ firstWorldFrame?(): IStartupImageState;
200
+ /**
201
+ * Performs one covered output-pipeline render without marking first present. `afterDraw` runs in
202
+ * the same task as every draw it makes, the frame gate's retries included, to repaint a cover.
203
+ */
204
+ warmUpWorldPass?(
205
+ scene: Object3D,
206
+ camera: Camera,
207
+ targetScene?: Object3D,
208
+ afterDraw?: () => void,
209
+ ): void | Promise<void>;
185
210
  /**
186
211
  * What alpha antialiasing did with the multisampled surface, and why, when it did nothing.
187
212
  *
@@ -390,6 +415,9 @@ export interface IRendererLike {
390
415
  * caller; a pinned game never reaches this, which is what makes "pinned" mean pinned.
391
416
  */
392
417
  setResolutionScale(scale: number, scaleSource: "auto" | "auto-pinned"): void;
418
+ /** True only while the owned temporal resolve reconstructs display pixels. */
419
+ temporalUpscale?(): boolean;
420
+ temporalUpscaleStartScale?(): number | undefined;
393
421
  /**
394
422
  * What this renderer is actually drawing at. Read once per frame-budget window so every fps
395
423
  * number is self-describing; a record and a tree once disagreed about the scale for a whole
@@ -421,6 +449,13 @@ export interface IRendererOptions {
421
449
  alphaAntialiasing?: boolean;
422
450
  /** Requests multisample antialiasing from the renderer. Defaults to true. */
423
451
  antialias?: boolean;
452
+ /**
453
+ * The tone curve a WebGPU renderer starts with. Defaults to `filmic`, a fresh Unreal 5.8.3
454
+ * project's curve; `aces`, `agx`, `neutral` and `none` (three's linear output) are the named
455
+ * overrides. A renderer that cannot run the curve keeps ACES and reports `TN_TONEMAP`. Setting
456
+ * `renderer.raw.toneMapping` afterwards still wins.
457
+ */
458
+ toneMapping?: RendererToneMapping;
424
459
  canvas?: HTMLCanvasElement;
425
460
  gpuTimestampFrameInterval?: number;
426
461
  preferWebGPU?: boolean;
@@ -452,6 +487,8 @@ export interface IRendererOptions {
452
487
  }
453
488
 
454
489
  type RendererInstance = IStorageBufferSource & {
490
+ readonly temporalUpscale?: boolean;
491
+ setRenderScale?(scale: number): void;
455
492
  autoClear?: boolean;
456
493
  /** three's resolved GPU timings; `info.render.timestamp` is milliseconds. */
457
494
  info?: {
@@ -544,8 +581,9 @@ export function readCanvasSize(canvas: HTMLCanvasElement): readonly [number, num
544
581
  }
545
582
 
546
583
  export function observeCanvasResize(canvas: HTMLCanvasElement, resize: () => void): () => void {
547
- if (typeof ResizeObserver !== "undefined") {
548
- const observer = new ResizeObserver(resize);
584
+ const Observer = hostResizeObserver();
585
+ if (Observer !== undefined) {
586
+ const observer = new Observer(resize);
549
587
  observer.observe(canvas);
550
588
  return () => observer.disconnect();
551
589
  }
@@ -652,6 +690,8 @@ function wrapRenderer(
652
690
  let pendingSize: Parameters<IRendererLike["setSize"]> | undefined;
653
691
  let timestampFrame = -1;
654
692
  let timestampFramesManaged = false;
693
+ // The world submission count a held startup started at: only a frame drawn after it is this one.
694
+ let presentationSince = 0;
655
695
  const pyramidQueries: string[][] = [];
656
696
  let gpuObservation: GpuFrameObservation | undefined;
657
697
  let gpuObservationGeneration = 0;
@@ -715,7 +755,13 @@ function wrapRenderer(
715
755
  };
716
756
 
717
757
  let renderingFrame = 0;
758
+ let temporalUpscaleActive = false;
718
759
  const renderFrame = (scene: Object3D, camera: Camera): void => {
760
+ const temporal = wrapped.temporalUpscale?.() === true;
761
+ if (temporal !== temporalUpscaleActive) {
762
+ temporalUpscaleActive = temporal;
763
+ reapply.resize?.();
764
+ }
719
765
  pipelineCensus?.beginWorldFrame(scene);
720
766
  const refreshPass = pendingWorldPassRefresh ? outputPass : undefined;
721
767
  const restoreWorldPass = refreshWorldPassOnce(refreshPass);
@@ -738,8 +784,32 @@ function wrapRenderer(
738
784
  pipelineCensus?.endWorldFrame(scene, completed);
739
785
  }
740
786
  };
787
+ let overlayReported = false;
741
788
  const renderOverlayFrame = (scene: Object3D, camera: Camera): void => {
742
789
  bindSurface();
790
+ // The owned engine draws an overlay over the presented frame with no post, no temporal step and
791
+ // no tone curve; through its render() the loading screen moved the world's temporal history and
792
+ // exposure (a ghosted hand-off).
793
+ const overlay = (raw as { renderOverlay?: (scene: Object3D, camera: Camera) => void })
794
+ .renderOverlay;
795
+ // The canvas layer is UI, and UI composites after the tone curve, as Unreal draws Slate onto the
796
+ // already tone-mapped back buffer (UE 5.8.3: Engine/Source/Runtime/SlateRHIRenderer/Private/
797
+ // SlateRHIRenderer.cpp:986 and :1032). Reported, because three's WebGPURenderer cannot: it tone
798
+ // maps the canvas layer and the world below it in one output pass over a shared frame buffer.
799
+ if (!overlayReported) {
800
+ overlayReported = true;
801
+ console.log(
802
+ `TN_CANVAS_LAYER:${JSON.stringify(
803
+ overlay !== undefined
804
+ ? { toneMapping: "none", composite: "after the tone curve" }
805
+ : { toneMapping: "renderer", composite: "with the world in three's output pass" },
806
+ )}`,
807
+ );
808
+ }
809
+ if (overlay !== undefined) {
810
+ overlay.call(raw, scene, camera);
811
+ return;
812
+ }
743
813
  const hadOwnAutoClear = Object.hasOwn(raw, "autoClear");
744
814
  const autoClear = raw.autoClear;
745
815
  raw.autoClear = false;
@@ -797,7 +867,11 @@ function wrapRenderer(
797
867
  }),
798
868
  get warmUpWorldPass() {
799
869
  if (outputPipeline === undefined) return undefined;
800
- return (scene: Object3D, camera: Camera, targetScene?: Object3D): void | Promise<void> => {
870
+ const drawOnce = (
871
+ scene: Object3D,
872
+ camera: Camera,
873
+ targetScene?: Object3D,
874
+ ): void | Promise<void> => {
801
875
  const outputRoot = targetScene ?? scene;
802
876
  const scoped = targetScene !== undefined && targetScene !== scene;
803
877
  const previousPassScene = outputPass?.scene;
@@ -908,8 +982,28 @@ function wrapRenderer(
908
982
  // no async cache still returns synchronously, exactly as before.
909
983
  return asyncPipelines?.settled();
910
984
  };
985
+ return (
986
+ scene: Object3D,
987
+ camera: Camera,
988
+ targetScene?: Object3D,
989
+ afterDraw?: () => void,
990
+ ): void | Promise<void> =>
991
+ drawPastFrameGate(raw, () => drawOnce(scene, camera, targetScene), undefined, afterDraw);
911
992
  },
912
993
  gpuFrameMs: () => gpuFrameSample()?.ms,
994
+ // Present only on the Wasm engine: its host can hold the canvas while core keeps drawing. Every other
995
+ // renderer presents every frame it draws, exactly as before, and `game.ts` checks for the seam.
996
+ ...(typeof (raw as { setPresentationHeld?: unknown }).setPresentationHeld === "function"
997
+ ? {
998
+ setPresentationHeld: (held: boolean): void => {
999
+ // Captured where the hold engages, so a frame drawn before this startup began can never release it.
1000
+ if (held) presentationSince = rendererStartupFrames(raw)?.submissions ?? 0;
1001
+ (raw as { setPresentationHeld?: (held: boolean) => void }).setPresentationHeld?.(held);
1002
+ },
1003
+ firstWorldFrame: (): IStartupImageState =>
1004
+ rendererFirstWorldFrame(raw, presentationSince),
1005
+ }
1006
+ : {}),
913
1007
  gpuFrameAge: () => {
914
1008
  const sample = gpuFrameSample();
915
1009
  const frame = currentFrame();
@@ -924,7 +1018,11 @@ function wrapRenderer(
924
1018
  disposed ||
925
1019
  kind !== "webgpu" ||
926
1020
  !timestampCapable ||
927
- typeof raw.resolveTimestampsAsync !== "function"
1021
+ typeof raw.resolveTimestampsAsync !== "function" ||
1022
+ // Three's backend creates the pool record at construction; a backend without it (the owned web
1023
+ // engine's facade) never allocates one, so an observer would wait on it forever.
1024
+ raw.backend === undefined ||
1025
+ !("timestampQueryPool" in raw.backend)
928
1026
  )
929
1027
  throw new Error("TN_GPU_FRAME_OBSERVATION_UNSUPPORTED");
930
1028
  if (gpuObservation !== undefined && gpuObservation.status().state !== "disposed")
@@ -1332,6 +1430,8 @@ function wrapRenderer(
1332
1430
  try {
1333
1431
  storageBuffers.dispose();
1334
1432
  } finally {
1433
+ // A renderer disposed mid-startup takes no hold with it: the next one presents its own first frame.
1434
+ (raw as { setPresentationHeld?: (held: boolean) => void }).setPresentationHeld?.(false);
1335
1435
  raw.dispose?.();
1336
1436
  }
1337
1437
  },
@@ -1405,6 +1505,24 @@ function wrapRenderer(
1405
1505
  state.resolutionSubrect = undefined;
1406
1506
  reapply.resize?.();
1407
1507
  },
1508
+ temporalUpscale: () =>
1509
+ typeof raw.setRenderScale === "function" &&
1510
+ (renderChains.size === 0
1511
+ ? raw.temporalUpscale === true
1512
+ : outputPipeline !== undefined &&
1513
+ [...renderChains].some(
1514
+ (chain) => !chain.disposed && chain.applied.stages.includes("traa"),
1515
+ )),
1516
+ temporalUpscaleStartScale: () => {
1517
+ if (!wrapped.temporalUpscale?.()) return undefined;
1518
+ const chain = [...renderChains].find(
1519
+ (candidate) => !candidate.disposed && candidate.applied.stages.includes("traa"),
1520
+ );
1521
+ const tier = chain?.applied.tier;
1522
+ return tier === "high" || tier === "medium" || tier === "low"
1523
+ ? qualityTiers.resolutionScale[tier]
1524
+ : qualityTiers.resolutionScale[qualityTiers.resolve({ gpuClass: gpuClass?.class })];
1525
+ },
1408
1526
  renderChainUsesPerObjectVelocity: () => renderChainUsesPerObjectVelocity,
1409
1527
  setRenderChainVelocityEnabled: (enabled) => {
1410
1528
  renderChainUsesPerObjectVelocity = enabled;
@@ -1416,6 +1534,7 @@ function wrapRenderer(
1416
1534
  renderChains.clear();
1417
1535
  const chain = new RenderChain(wrapped, options);
1418
1536
  renderChains.add(chain);
1537
+ reapply.resize?.();
1419
1538
  return chain;
1420
1539
  },
1421
1540
  observeRenderChainBudget: (window) => {
@@ -1454,6 +1573,131 @@ function isOutputPassNode(node: unknown): node is PassNode {
1454
1573
  return isObject(node) && node.isPassNode === true;
1455
1574
  }
1456
1575
 
1576
+ /** How long a covered warm-up draw waits for the GPU to take a frame before it fails. */
1577
+ const FRAME_GATE_WAIT_MS = 5000;
1578
+
1579
+ /** Cumulative render() calls the renderer declined to draw (the Wasm web engine's frame gate), when it counts them. */
1580
+ export function rendererFrameGateSkips(raw: unknown): number | undefined {
1581
+ const info = (raw as { info?: { engine?: { frameGateSkips?: unknown } } } | null)?.info;
1582
+ const skips = info?.engine?.frameGateSkips;
1583
+ return typeof skips === "number" && Number.isFinite(skips) ? skips : undefined;
1584
+ }
1585
+
1586
+ /**
1587
+ * Whether the first world frame drawn after the hold came off has finished on the GPU, so the display shows it.
1588
+ * `undefined` for a renderer with no engine report (it has no such answer, and the hand-off then counts draws as before).
1589
+ */
1590
+ export function rendererWorldPresented(raw: unknown): boolean | undefined {
1591
+ const startup = (raw as { info?: { engine?: { startup?: { worldPresented?: unknown } } } } | null)
1592
+ ?.info?.engine?.startup;
1593
+ return typeof startup?.worldPresented === "boolean" ? startup.worldPresented : undefined;
1594
+ }
1595
+
1596
+ /**
1597
+ * Whether the renderer is drawing under the loading cover to finish its environment bake. A bake
1598
+ * draw presents nothing and its world is still unlit, so its pixels are not the view's first frame:
1599
+ * the eye adaptation must not adopt them. A renderer without an engine report answers false.
1600
+ */
1601
+ export function rendererEnvironmentBake(raw: unknown): boolean {
1602
+ const info = (raw as { info?: { engine?: { environmentBake?: unknown } } } | null)?.info;
1603
+ return info?.engine?.environmentBake === true;
1604
+ }
1605
+
1606
+ /**
1607
+ * Where the `WorldEnvironment` that owns the exposure meter publishes its startup readiness. One
1608
+ * symbol in the global registry, so the look layer's install and this read agree without an import
1609
+ * either way.
1610
+ */
1611
+ export const STARTUP_EXPOSURE = Symbol.for("threenative.startupExposure");
1612
+
1613
+ /**
1614
+ * The owning exposure install's answer, or true when nothing installed one: a scene with no auto
1615
+ * exposure, or a renderer that runs none, has no meter to wait for.
1616
+ */
1617
+ export function rendererStartupExposureReady(raw: unknown): boolean {
1618
+ const probe = (raw as Record<symbol, unknown> | null | undefined)?.[STARTUP_EXPOSURE];
1619
+ return typeof probe !== "function" ? true : (probe as () => boolean)() === true;
1620
+ }
1621
+
1622
+ /**
1623
+ * The Wasm engine's startup frame report (`tnw_web_frame` fields 71 and 72): the ordinary world
1624
+ * submissions that encoded since the page started drawing, and whether the shadow inputs such a
1625
+ * frame samples exist. A frame the environment bake gated, an overlay, a declined draw and a failed
1626
+ * one are all absent from the count. A renderer without the report answers undefined.
1627
+ */
1628
+ export function rendererStartupFrames(
1629
+ raw: unknown,
1630
+ ): { readonly shadowInputsReady: boolean; readonly submissions: number } | undefined {
1631
+ const startup = (
1632
+ raw as {
1633
+ info?: {
1634
+ engine?: { startup?: { shadowInputsReady?: unknown; worldSubmissions?: unknown } };
1635
+ };
1636
+ } | null
1637
+ )?.info?.engine?.startup;
1638
+ const submissions = startup?.worldSubmissions;
1639
+ if (typeof submissions !== "number" || !Number.isFinite(submissions)) return undefined;
1640
+ return { shadowInputsReady: startup?.shadowInputsReady === true, submissions };
1641
+ }
1642
+
1643
+ /**
1644
+ * A held startup's first world frame, for the generation `since` starts at: `ready` once an ordinary
1645
+ * submission drew after it, that frame's shadow inputs are initialized, and this install's auto exposure
1646
+ * measured within 3% of its target; `shadowInputsReady` and `exposureSettled` say which one is still cold, so
1647
+ * the deadline line names what never arrived. The settled flag alone permits a 0.25-stop error, about 19%, so
1648
+ * the stops themselves are compared. A renderer with no startup report answers ready, which keeps every other
1649
+ * renderer's path unchanged.
1650
+ */
1651
+ export function rendererFirstWorldFrame(raw: unknown, since: number): IStartupImageState {
1652
+ const frames = rendererStartupFrames(raw);
1653
+ if (frames === undefined) return { exposureSettled: true, ready: true, shadowInputsReady: true };
1654
+ const exposureSettled = rendererStartupExposureReady(raw);
1655
+ const shadowInputsReady = frames.submissions > since && frames.shadowInputsReady;
1656
+ return {
1657
+ exposureSettled,
1658
+ ready: exposureSettled && shadowInputsReady,
1659
+ shadowInputsReady,
1660
+ };
1661
+ }
1662
+
1663
+ /**
1664
+ * Runs a covered warm-up draw until the renderer takes it. The Wasm web engine's frame gate declines
1665
+ * a draw while two frames are still on the GPU, and a declined draw compiles nothing: on Lantern Vale
1666
+ * the startup pass was declined, so the TRAA, aux and post pipelines (92) compiled synchronously
1667
+ * 1.1 s after the reveal and stalled the queue for 2.3 s. A renderer with no gate, or one that took
1668
+ * the first draw, returns that draw's result unchanged. `afterDraw` runs straight after every draw,
1669
+ * in its task: a retry presents on its own, and a cover painted only after the declined first call
1670
+ * left Hop Garden's world showing through it for one frame.
1671
+ */
1672
+ export function drawPastFrameGate(
1673
+ raw: unknown,
1674
+ draw: () => void | Promise<void>,
1675
+ waitMs = FRAME_GATE_WAIT_MS,
1676
+ afterDraw?: () => void,
1677
+ ): void | Promise<void> {
1678
+ const before = rendererFrameGateSkips(raw);
1679
+ const first = draw();
1680
+ afterDraw?.();
1681
+ if (before === undefined || rendererFrameGateSkips(raw) === before) return first;
1682
+ const now = (): number => globalThis.performance?.now() ?? Date.now();
1683
+ return (async () => {
1684
+ await first;
1685
+ // The wait starts once the declined draw settled, so a slow settle does not use up the retries.
1686
+ const deadline = now() + waitMs;
1687
+ while (now() < deadline) {
1688
+ await new Promise((resolve) => setTimeout(resolve, 16));
1689
+ const skips = rendererFrameGateSkips(raw);
1690
+ const drawn = draw();
1691
+ afterDraw?.();
1692
+ if (rendererFrameGateSkips(raw) === skips) return drawn;
1693
+ await drawn;
1694
+ }
1695
+ throw new Error(
1696
+ `TN_WARMUP_FRAME_GATE: the covered warm-up draw waited ${waitMs} ms for the GPU to take a frame and never drew.`,
1697
+ );
1698
+ })();
1699
+ }
1700
+
1457
1701
  function selectOutputPass(node: unknown, worldPass: unknown): PassNode | undefined {
1458
1702
  return outputPassOf(worldPass) ?? outputPassOf(node) ?? findSoleOutputPass(node);
1459
1703
  }
@@ -1543,7 +1787,13 @@ function addResizeHandling(
1543
1787
  // the host's to define and on native they have been the physical surface, which is exactly
1544
1788
  // the number this scale exists to stop a game from paying by hand.
1545
1789
  const subrect = state.resolutionSubrect;
1546
- const scale = subrect?.active ? 1 : state.resolutionScale;
1790
+ const temporal =
1791
+ renderer.temporalUpscale?.() === true &&
1792
+ state.resolutionScale >= 0.25 &&
1793
+ state.resolutionScale <= 1;
1794
+ const owned = renderer.raw as RendererInstance;
1795
+ owned.setRenderScale?.(temporal ? state.resolutionScale : 1);
1796
+ const scale = subrect?.active || temporal ? 1 : state.resolutionScale;
1547
1797
  const physicalWidth = Math.max(1, Math.round(width * pixelRatio * scale));
1548
1798
  const physicalHeight = Math.max(1, Math.round(height * pixelRatio * scale));
1549
1799
  applied = [physicalWidth, physicalHeight];
@@ -1687,6 +1937,9 @@ const TEXTURE_LIMITS = {
1687
1937
  // three stores every morph target of a mesh as one layer of a texture array: a MetaHuman head
1688
1938
  // carries 821, and past the default 256 the mesh never draws.
1689
1939
  maxTextureArrayLayers: 256,
1940
+ // Seven RGBA16Float render targets carry 56 bytes per sample; the device default of 32 invalidates
1941
+ // the pipeline even when the adapter reports 128.
1942
+ maxColorAttachmentBytesPerSample: 32,
1690
1943
  } as const;
1691
1944
 
1692
1945
  /**
@@ -1719,6 +1972,15 @@ export async function adapterTextureLimits(): Promise<{ requiredLimits?: Record<
1719
1972
  }
1720
1973
  }
1721
1974
 
1975
+ function newPageCanvas(): HTMLCanvasElement {
1976
+ const page = hostDocument();
1977
+ if (page === undefined)
1978
+ throw new Error(
1979
+ "TN_RENDERER_NO_CANVAS: no canvas was given and this host has no document; pass options.canvas",
1980
+ );
1981
+ return page.createElement("canvas");
1982
+ }
1983
+
1722
1984
  export async function createRenderer(options: IRendererOptions = {}): Promise<IRendererLike> {
1723
1985
  const source = options.source;
1724
1986
  const gpuTimestampFrameInterval =
@@ -1738,7 +2000,7 @@ export async function createRenderer(options: IRendererOptions = {}): Promise<IR
1738
2000
  if (!Number.isFinite(resolutionScale) || resolutionScale <= 0)
1739
2001
  throw new Error("renderer.resolutionScale must be finite and positive.");
1740
2002
  const applied = { height: 1, width: 1 };
1741
- const canvas = options.canvas ?? source?.createCanvas() ?? document.createElement("canvas");
2003
+ const canvas = options.canvas ?? source?.createCanvas() ?? newPageCanvas();
1742
2004
  // An intrinsic canvas follows its width/height attributes. Scaling that buffer then changes
1743
2005
  // clientWidth, so ResizeObserver scales it again until it is one pixel. Own the layout only
1744
2006
  // for the browser canvas we created; supplied canvases and platform surfaces own theirs.
@@ -1764,18 +2026,27 @@ export async function createRenderer(options: IRendererOptions = {}): Promise<IR
1764
2026
  sampleCount: () => resolveSampleCount(raw),
1765
2027
  });
1766
2028
  let renderer: IRendererLike | undefined;
2029
+ // Why WebGPU did not start, when it was tried: the boot failure must name it, or a fault in the
2030
+ // WebGPU path (PRD-752: a DOM-only canvas call in a worker) reads as a device without WebGPU.
2031
+ let webgpuFailure: string | undefined;
1767
2032
 
1768
2033
  if (preferWebGPU && (source?.hasWebGPU() ?? "gpu" in (globalThis.navigator ?? {}))) {
1769
2034
  try {
1770
2035
  const raw = options.webgpuFactory
1771
2036
  ? await options.webgpuFactory(canvas, rendererParameters)
1772
- : new (await import("three/webgpu")).WebGPURenderer({
1773
- canvas,
1774
- ...rendererParameters,
1775
- ...(await adapterTextureLimits()),
2037
+ : await import("three/webgpu").then(async (webgpu) => {
2038
+ // Two Sided Foliage lets the sun through on three's lit node materials too (PRD-643).
2039
+ (await import("./render/two-sided-foliage.js")).installFoliageTransmission(webgpu);
2040
+ return new webgpu.WebGPURenderer({
2041
+ canvas,
2042
+ ...rendererParameters,
2043
+ ...(await adapterTextureLimits()),
2044
+ });
1776
2045
  });
1777
2046
  const instance = raw as RendererInstance;
1778
2047
  await instance.init?.();
2048
+ // A game that sets `toneMapping` on the renderer later (WorldEnvironment, Daylight) replaces this.
2049
+ applyRendererToneMapping(instance, options.toneMapping ?? "filmic", report);
1779
2050
  const alphaAntialiasing = arm(instance);
1780
2051
  const timestampCapable = instance.backend?.trackTimestamp === true;
1781
2052
  const adapter = await readWebGpuAdapterFacts(instance);
@@ -1796,7 +2067,11 @@ export async function createRenderer(options: IRendererOptions = {}): Promise<IR
1796
2067
  );
1797
2068
  if (adapter.gpuClass !== undefined)
1798
2069
  report(`${GPU_CLASS_MARKER}:${JSON.stringify(adapter.gpuClass)}`);
1799
- } catch {
2070
+ } catch (error) {
2071
+ // A facade and Wasm engine from two builds is an install fault, not a device without
2072
+ // WebGPU: falling back would report TN_NO_RENDERER and hide the fix.
2073
+ if (error instanceof Error && error.message.startsWith("TN_WASM_ABI_MISMATCH")) throw error;
2074
+ webgpuFailure = error instanceof Error ? error.message : String(error);
1800
2075
  renderer = undefined;
1801
2076
  }
1802
2077
  }
@@ -1815,7 +2090,7 @@ export async function createRenderer(options: IRendererOptions = {}): Promise<IR
1815
2090
  // verbatim would show an internal "uncatalogued" code; a browser with no context throws
1816
2091
  // three's own message. Neither belongs in front of a player, so both become one named failure.
1817
2092
  throw new Error(
1818
- "TN_NO_RENDERER: WebGPU is not available on this device and the WebGL fallback could not start, so the game cannot run.",
2093
+ `TN_NO_RENDERER: WebGPU is not available on this device and the WebGL fallback could not start, so the game cannot run.${webgpuFailure === undefined ? "" : ` WebGPU failed: ${webgpuFailure}`}`,
1819
2094
  { cause: error },
1820
2095
  );
1821
2096
  }
@@ -32,12 +32,17 @@ export const RESOLUTION_SCALER = {
32
32
  * The ladder above is the device arm's, and it ends at 0.23 because a phone buys the pixels back
33
33
  * differently. A desktop has nothing: no temporal stage, no reconstruction, just 5% of the
34
34
  * pixels stretched across the panel, which is blocky mush rather than a slow frame — and the
35
- * report at that point claims the budget was met. 0.61 is where surrendering more pixels stops
36
- * buying frame time worth what it costs to look at, and it is reported as `atFloor` rather than
37
- * passed in silence. A host whose chain *does* reconstruct the frame says so, and the deep
38
- * rungs come back; `renderer-config.ts` decides which floor a platform starts with.
35
+ * report at that point claims the budget was met. The floor was 0.61 until 2026-10-24, when the
36
+ * owner played Hop Garden at 30 fps on a faster panel and read the stretched 0.61 frame as a
37
+ * blur over everything. Unreal ships dynamic resolution off (UE 5.8.3:
38
+ * Engine/Source/Runtime/Engine/Private/UnrealEngine.cpp:538-542, `r.DynamicRes.OperationMode`
39
+ * 0; GameUserSettings.cpp:329, `bUseDynamicResolution = false`) and only drops pixels under a
40
+ * temporal upscaler, so a desktop holds full resolution and reports `atFloor` and one
41
+ * `TN_RESOLUTION_FLOOR` line rather than a met budget. A host whose chain *does* reconstruct the
42
+ * frame says so, and the rungs come back; `renderer-config.ts` decides which floor a platform
43
+ * starts with, and a pinned `renderer.resolutionScale` still lowers it on purpose.
39
44
  */
40
- desktopFloorScale: 0.61,
45
+ desktopFloorScale: 1,
41
46
  /**
42
47
  * The rung a class of adapter starts on instead of the ceiling; a class not named here starts at
43
48
  * 1.0. Only `mobile-low` moves: one rung down is 0.85, close to the 0.8 content scale Unreal's
@@ -170,6 +175,8 @@ export const RESOLUTION_SCALER = {
170
175
 
171
176
  /** Printed when a downward step is refunded because the frame did not respond to the pixels. */
172
177
  export const RESOLUTION_SCALE_INSENSITIVE_MARKER = "TN_RESOLUTION_SCALE_INSENSITIVE";
178
+ /** Printed once, the first window the scaler is out of room, with the floor's reason. */
179
+ export const RESOLUTION_FLOOR_MARKER = "TN_RESOLUTION_FLOOR";
173
180
 
174
181
  /** Pixels retained per rung: 0.85 linear on each axis. */
175
182
  const RUNG_PIXEL_RATIO = 0.85 * 0.85;
@@ -217,6 +224,12 @@ export interface IScalerWindow {
217
224
  readonly fps: number;
218
225
  /** Loop frames represented by this closed window, used for the sub-rectangle cadence guard. */
219
226
  readonly frames?: number;
227
+ /**
228
+ * Loop frames of the window whose render the renderer declined (the Wasm web engine's gate while
229
+ * two frames are on the GPU). A declined frame shows nothing new, so the rate the panel saw is
230
+ * `fps * (frames - renderSkips) / frames`, and `presented`, the loop's cadence, does not show them.
231
+ */
232
+ readonly renderSkips?: number;
220
233
  /** Current drawing surface, used to quantize a continuous estimate to eight pixels. */
221
234
  readonly surface?: {
222
235
  readonly drawingBufferWidth: number;
@@ -255,6 +268,7 @@ export class ResolutionScaler {
255
268
  /** The lowest rung this platform may take; the whole ladder's last index when it states none. */
256
269
  readonly #minIndex: number;
257
270
  readonly #temporalUpscale: (() => boolean) | undefined;
271
+ #hadTemporalUpscale = false;
258
272
  #scaleSource: Exclude<ScaleSource, "pinned"> = "auto";
259
273
  #cleanWindows = 0;
260
274
  #cooldown = 0;
@@ -331,7 +345,10 @@ export class ResolutionScaler {
331
345
  * as the render chain reconstructs the frame from the pixels it is being asked to surrender.
332
346
  */
333
347
  get #limitIndex(): number {
334
- return this.#temporalUpscale?.() === true ? RESOLUTION_SCALER.rungs.length - 1 : this.#minIndex;
348
+ // UE 5.8.3 SceneView.h:2280: temporal upsampling admits fractions >= 0.25.
349
+ return this.#temporalUpscale?.() === true
350
+ ? RESOLUTION_SCALER.rungs.indexOf(0.27)
351
+ : this.#minIndex;
335
352
  }
336
353
 
337
354
  get scaleSource(): Exclude<ScaleSource, "pinned"> {
@@ -353,6 +370,31 @@ export class ResolutionScaler {
353
370
  * step, `undefined` otherwise. Allocation-free: no object is constructed on the steady path.
354
371
  */
355
372
  observe(window: IScalerWindow): number | undefined {
373
+ const step = this.#observeWindow(window);
374
+ if (this.#atFloor && !this.#floorReported) {
375
+ this.#floorReported = true;
376
+ // The platform's own floor holds above the ladder's end only where nothing reconstructs.
377
+ const reason =
378
+ this.#limitIndex < RESOLUTION_SCALER.rungs.length - 1 ? "no-reconstruction" : "ladder-end";
379
+ console.info(
380
+ `${RESOLUTION_FLOOR_MARKER} scale=${String(this.scale)} reason=${reason} override=renderer.resolutionScale`,
381
+ );
382
+ }
383
+ return step;
384
+ }
385
+ #floorReported = false;
386
+
387
+ #observeWindow(observed: IScalerWindow): number | undefined {
388
+ const window = drawnWindow(observed);
389
+ const temporal = this.#temporalUpscale?.() === true;
390
+ const removed = this.#hadTemporalUpscale && !temporal;
391
+ this.#hadTemporalUpscale = temporal;
392
+ if (removed && this.scale < (RESOLUTION_SCALER.rungs[this.#minIndex] ?? 0.23)) {
393
+ // Losing the reconstructor restores the platform floor even during cooldown or an automatic pin.
394
+ this.#scaleSource = "auto";
395
+ this.#pinWindows = 0;
396
+ return this.#step(this.#minIndex - this.#index, false);
397
+ }
356
398
  this.#windowIndex += 1;
357
399
  const frames = window.frames;
358
400
  this.#continuousFrames +=
@@ -727,7 +769,12 @@ export class ResolutionScaler {
727
769
  }
728
770
 
729
771
  #overBudget(window: IScalerWindow): boolean {
730
- return window.presented.p50 > this.budgetMs || window.presented.p95 > this.tailMs;
772
+ return (
773
+ window.presented.p50 > this.budgetMs ||
774
+ window.presented.p95 > this.tailMs ||
775
+ // The loop kept the cadence by declining draws: the drawn frames' mean interval is the cost.
776
+ ((window.renderSkips ?? 0) > 0 && 1000 / window.fps > this.budgetMs)
777
+ );
731
778
  }
732
779
 
733
780
  #freshGpuMs({ gpu, gpuMs, gpuAgeFrames }: IScalerWindow): number | undefined {
@@ -817,3 +864,14 @@ export class ResolutionScaler {
817
864
  this.#pinWindows = RESOLUTION_SCALER.oscillationWindows;
818
865
  }
819
866
  }
867
+
868
+ /**
869
+ * The window as the panel saw it: `fps` of the frames drawn, not of the loop. Lantern Vale on Iris
870
+ * Xe declined 105 of 300 renders at 25 ms of GPU each; the loop's 59.88 fps held the scale at 1.
871
+ */
872
+ function drawnWindow(window: IScalerWindow): IScalerWindow {
873
+ const { frames, renderSkips } = window;
874
+ if (renderSkips === undefined || renderSkips <= 0 || frames === undefined || !(frames > 0))
875
+ return window;
876
+ return { ...window, fps: (window.fps * Math.max(0, frames - renderSkips)) / frames };
877
+ }
@@ -11,6 +11,8 @@ export interface ISkeletalMesh3DOptions {
11
11
  readonly size?: INormaliseToMetresOptions;
12
12
  readonly strideRoot?: Object3D;
13
13
  readonly strideSync?: boolean;
14
+ readonly updateRate?: "auto" | number;
15
+ readonly gpuPose?: boolean;
14
16
  }
15
17
 
16
18
  export class SkeletalMesh3D extends AnimationPlayer {
@@ -24,6 +26,8 @@ export class SkeletalMesh3D extends AnimationPlayer {
24
26
  root,
25
27
  strideRoot: options.strideRoot ?? root,
26
28
  strideSync: options.strideSync,
29
+ updateRate: options.updateRate,
30
+ gpuPose: options.gpuPose,
27
31
  preparation: rigPreparation(options.source),
28
32
  });
29
33
  if (options.size !== undefined) {