@threenative/core 0.3.5 → 0.3.8

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-Bj8G1wmD.d.ts → game-cb99J-YE.d.ts} +112 -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 +22445 -12411
  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 +59 -10
  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 +544 -106
  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 +40 -6
  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 +69 -12
  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
@@ -84,11 +84,20 @@ export interface IProbeVolumeOptions {
84
84
  readonly bounds: Box3 | { readonly min: IVector3Like; readonly max: IVector3Like };
85
85
  /** Probe spacing expressed as probes per world unit. */
86
86
  readonly density: ProbeVolumeDensity;
87
+ /**
88
+ * Where the atlas is rendered. `auto` (default) probes the device: a host that rejects a 3D render
89
+ * attachment (wgpu-native) renders each slice into a 2D target and copies it into the 3D atlas,
90
+ * and a host that accepts one renders into the atlas directly. `render3d` and `copy` force a path.
91
+ */
92
+ readonly atlasTarget?: "auto" | "render3d" | "copy";
87
93
  /** Optional device limit supplied by a host that knows it before construction. */
88
94
  readonly maxTextureDimension3D?: number;
89
95
  /** Alias for integrations that expose the WebGPU limit under a device-oriented name. */
90
96
  readonly deviceTextureLimit?: number;
91
- /** Maximum wall-clock work per render phase, in milliseconds. */
97
+ /**
98
+ * Maximum wall-clock work per render phase, in milliseconds. A work item that outruns it fails the
99
+ * bake, except on a CPU rasteriser (the renderer's `softwareAdapter`), where `bakeCostMs` reports it.
100
+ */
92
101
  readonly bakeBudgetMs?: number;
93
102
  /** Additional guard that keeps a clock-less host from processing an unbounded queue. */
94
103
  readonly maxWorkItemsPerFrame?: number;
@@ -136,14 +145,20 @@ export function readProbeVolumeObservation(value: unknown): IProbeVolumeObservat
136
145
  return isProbeVolumeObservation(value) ? value : undefined;
137
146
  }
138
147
 
148
+ interface IProbeDevice {
149
+ readonly limits?: Record<string, unknown>;
150
+ readonly createTexture?: (descriptor: unknown) => { readonly destroy?: () => void };
151
+ readonly popErrorScope?: () => Promise<unknown>;
152
+ readonly pushErrorScope?: (filter: string) => void;
153
+ }
154
+
139
155
  interface IProbeRenderer {
140
156
  readonly autoClear?: boolean;
141
157
  readonly compileAsync?: (scene: Object3D, camera: Camera) => Promise<void>;
142
158
  readonly coordinateSystem?: CoordinateSystem;
143
- readonly backend?: {
144
- readonly device?: { readonly limits?: Record<string, unknown> };
145
- };
146
- readonly device?: { readonly limits?: Record<string, unknown> };
159
+ readonly backend?: { readonly device?: IProbeDevice };
160
+ readonly device?: IProbeDevice;
161
+ readonly initTexture?: (texture: unknown) => void;
147
162
  readonly shadowMap?: { autoUpdate: boolean; needsUpdate: boolean };
148
163
  readonly toneMapping?: number;
149
164
  readonly toneMappingExposure?: number;
@@ -266,6 +281,11 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
266
281
  #projectionTarget: RenderTarget | undefined;
267
282
  #batchTarget: RenderTarget | undefined;
268
283
  #atlasTarget: RenderTarget3D | undefined;
284
+ #sliceTarget: RenderTarget | undefined;
285
+ readonly #requestedAtlasTarget: "auto" | "render3d" | "copy";
286
+ #atlasMode: "render3d" | "copy" | undefined;
287
+ #atlasProbeStarted = false;
288
+ #atlasUploaded = false;
269
289
  #quadScene: Scene | undefined;
270
290
  #quadCamera: OrthographicCamera | undefined;
271
291
  #quadMesh: Mesh | undefined;
@@ -293,6 +313,7 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
293
313
  this.#report = options.report ?? ((line) => console.info(line));
294
314
  this.#now = options.now ?? (() => globalThis.performance?.now() ?? Date.now());
295
315
  this.#bakeBudgetMs = positiveNumber(options.bakeBudgetMs ?? 2, "bakeBudgetMs");
316
+ this.#requestedAtlasTarget = options.atlasTarget ?? "auto";
296
317
  this.#maxWorkItemsPerFrame = positiveInteger(
297
318
  options.maxWorkItemsPerFrame ?? 1,
298
319
  "maxWorkItemsPerFrame",
@@ -349,6 +370,11 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
349
370
  return this.#atlasTexture;
350
371
  }
351
372
 
373
+ /** The atlas render path in use; `undefined` until the device probe settles. */
374
+ get atlasTarget(): "render3d" | "copy" | undefined {
375
+ return this.#atlasMode;
376
+ }
377
+
352
378
  get atlasDepth(): number {
353
379
  return this.#atlasDepth;
354
380
  }
@@ -415,6 +441,7 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
415
441
  const raw = renderer.raw as IProbeRenderer;
416
442
  const deviceLimit = readTextureLimit(raw);
417
443
  if (deviceLimit !== undefined) assertTextureLimit(this.maximumDimension, deviceLimit);
444
+ this.#startAtlasProbe(raw);
418
445
  this.#ensureGpuResources();
419
446
  if (this.#pending !== undefined) this.#prepareBake(this.#pending.scene, this.#pending.passes);
420
447
  }
@@ -509,11 +536,29 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
509
536
  return result.max(new Vector3());
510
537
  }
511
538
 
512
- /** The GPU graph used by `sample`; exposed so generated materials can compose it explicitly. */
513
- sampleNode(
514
- position: Node<"vec3"> = positionWorld,
515
- normal: Node<"vec3"> = normalWorld,
516
- ): Node<"vec3"> {
539
+ /**
540
+ * The irradiance averaged over every normal at a point, for a surface or a sample that has no side facing the light:
541
+ * a translucent pane (Unreal's default Volumetric NonDirectional lighting) and a fog sample (its isotropic term). It
542
+ * is the L0 coefficient, `0.886227 * c0`, so it is the mean of `sample(position, n)` over any set of normals that
543
+ * integrates the L2 basis, the six axes among them. It reads one atlas texel, where `sample` reads seven.
544
+ *
545
+ * Divide by pi for the mean radiance a fog sample scatters, and multiply by the colour for a pane: the volume owns
546
+ * no colour.
547
+ */
548
+ sampleNonDirectional(position: Vector3): Vector3;
549
+ sampleNonDirectional(position?: Node<"vec3">): Node<"vec3">;
550
+ sampleNonDirectional(position: IProbePosition = positionWorld): Vector3 | Node<"vec3"> {
551
+ if (position instanceof Vector3) {
552
+ const c = this.#samplePackedCoefficients(position);
553
+ return new Vector3(c[0] ?? 0, c[1] ?? 0, c[2] ?? 0)
554
+ .multiplyScalar(0.886227)
555
+ .max(new Vector3());
556
+ }
557
+ return this.#atlasNode.sample(this.#atlasAt(position)(0)).rgb.mul(0.886227).max(0);
558
+ }
559
+
560
+ /** The atlas coordinate of a world position inside each packed sub-volume. */
561
+ #atlasAt(position: Node<"vec3">): (subVolume: number) => Node<"vec3"> {
517
562
  const local = clamp(vec3(position).sub(this.#boundsMinNode).div(this.#boundsSizeNode), 0, 1);
518
563
  const atlasX = local.x
519
564
  .mul(this.resolution.x - 1)
@@ -524,13 +569,24 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
524
569
  .add(0.5)
525
570
  .div(this.resolution.y);
526
571
  const sliceStride = this.resolution.z + 2 * SAMPLE_ATLAS_PADDING;
527
- const atlasZ = (subVolume: number) =>
528
- local.z
529
- .mul(this.resolution.z - 1)
530
- .add(SAMPLE_ATLAS_PADDING + 0.5 + subVolume * sliceStride)
531
- .div(this.#atlasDepth);
532
- const packed = (subVolume: number) =>
533
- this.#atlasNode.sample(vec3(atlasX, atlasY, atlasZ(subVolume)));
572
+ return (subVolume) =>
573
+ vec3(
574
+ atlasX,
575
+ atlasY,
576
+ local.z
577
+ .mul(this.resolution.z - 1)
578
+ .add(SAMPLE_ATLAS_PADDING + 0.5 + subVolume * sliceStride)
579
+ .div(this.#atlasDepth),
580
+ );
581
+ }
582
+
583
+ /** The GPU graph used by `sample`; exposed so generated materials can compose it explicitly. */
584
+ sampleNode(
585
+ position: Node<"vec3"> = positionWorld,
586
+ normal: Node<"vec3"> = normalWorld,
587
+ ): Node<"vec3"> {
588
+ const atlasAt = this.#atlasAt(position);
589
+ const packed = (subVolume: number) => this.#atlasNode.sample(atlasAt(subVolume));
534
590
  const packedValues = Array.from({ length: PACKED_SUB_VOLUME_COUNT }, (_, index) =>
535
591
  packed(index),
536
592
  );
@@ -614,6 +670,7 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
614
670
  this.#publish(false);
615
671
  return;
616
672
  }
673
+ this.#ensureGpuResources();
617
674
  if (this.#sceneState === undefined)
618
675
  this.#prepareBake(this.#pending.scene, this.#pending.passes);
619
676
  this.#processPending(this.#pending);
@@ -634,6 +691,7 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
634
691
 
635
692
  #processPending(pending: IPendingBake): void {
636
693
  const started = this.#now();
694
+ const softwareRaster = this.#renderer?.softwareAdapter !== undefined;
637
695
  let workItems = 0;
638
696
  try {
639
697
  while (this.#pending !== undefined && workItems < this.#maxWorkItemsPerFrame) {
@@ -644,12 +702,14 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
644
702
  const itemCostMs = Math.max(0, this.#now() - itemStarted);
645
703
  this.#maxWorkItemCostMs = Math.max(this.#maxWorkItemCostMs, itemCostMs);
646
704
  const elapsed = Math.max(0, this.#now() - started);
647
- if (itemCostMs > this.#bakeBudgetMs + BAKE_BUDGET_SLACK_MS) {
705
+ // A CPU rasteriser cannot hold a hardware frame budget: one cube-face draw costs 12 to 18 ms on
706
+ // SwiftShader. The bake still runs one measured item at a time; `bakeCostMs` reports the overrun.
707
+ if (!softwareRaster && itemCostMs > this.#bakeBudgetMs + BAKE_BUDGET_SLACK_MS) {
648
708
  throw new Error(
649
709
  `ProbeVolume bake work item cost ${itemCostMs}ms exceeds bakeBudgetMs ${this.#bakeBudgetMs}ms plus ${BAKE_BUDGET_SLACK_MS}ms scheduling slack.`,
650
710
  );
651
711
  }
652
- if (elapsed > this.#bakeBudgetMs + BAKE_BUDGET_SLACK_MS) {
712
+ if (!softwareRaster && elapsed > this.#bakeBudgetMs + BAKE_BUDGET_SLACK_MS) {
653
713
  throw new Error(
654
714
  `ProbeVolume bake frame cost ${elapsed}ms exceeds bakeBudgetMs ${this.#bakeBudgetMs}ms plus ${BAKE_BUDGET_SLACK_MS}ms scheduling slack.`,
655
715
  );
@@ -678,6 +738,7 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
678
738
  this.#projectionTarget?.dispose();
679
739
  this.#batchTarget?.dispose();
680
740
  this.#atlasTarget?.dispose();
741
+ this.#sliceTarget?.dispose();
681
742
  this.#emptyAtlasTexture.dispose();
682
743
  this.#projectionMaterial?.dispose();
683
744
  for (const material of this.#repackMaterials ?? []) material.dispose();
@@ -687,6 +748,7 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
687
748
  this.#projectionTarget = undefined;
688
749
  this.#batchTarget = undefined;
689
750
  this.#atlasTarget = undefined;
751
+ this.#sliceTarget = undefined;
690
752
  this.#projectionMaterial = undefined;
691
753
  this.#repackMaterials = undefined;
692
754
  this.#atlasTexture = createCpuAtlas(this.#atlasData, this.resolution, this.#atlasDepth);
@@ -708,8 +770,59 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
708
770
  );
709
771
  }
710
772
 
773
+ /**
774
+ * Ask the device whether it accepts a 3D render attachment, as the atlas target needs one. WebGPU
775
+ * names no capability for it, so the probe creates the texture inside a validation scope. The bake
776
+ * waits for the answer through `#gpuWarmupSettled`; a host with no error scopes keeps the 3D path.
777
+ */
778
+ #startAtlasProbe(raw: IProbeRenderer): void {
779
+ if (this.#atlasMode !== undefined || this.#atlasProbeStarted) return;
780
+ const device = raw.backend?.device ?? raw.device;
781
+ const { createTexture, popErrorScope, pushErrorScope } = device ?? {};
782
+ if (this.#requestedAtlasTarget !== "auto") {
783
+ this.#atlasMode = this.#requestedAtlasTarget;
784
+ } else if (
785
+ device === undefined ||
786
+ createTexture === undefined ||
787
+ popErrorScope === undefined ||
788
+ pushErrorScope === undefined
789
+ ) {
790
+ this.#atlasMode = "render3d";
791
+ } else {
792
+ this.#atlasProbeStarted = true;
793
+ this.#gpuWarmupSettled = false;
794
+ let probe: { readonly destroy?: () => void } | undefined;
795
+ let created = true;
796
+ pushErrorScope.call(device, "validation");
797
+ try {
798
+ // GPUTextureUsage.TEXTURE_BINDING | RENDER_ATTACHMENT, the usage of the atlas render target.
799
+ probe = createTexture.call(device, {
800
+ dimension: "3d",
801
+ format: "rgba32float",
802
+ size: [1, 1, 1],
803
+ usage: 0x04 | 0x10,
804
+ });
805
+ } catch {
806
+ created = false;
807
+ }
808
+ popErrorScope.call(device).then(
809
+ (error) =>
810
+ this.#settleAtlasProbe(created && (error === null || error === undefined), probe),
811
+ () => this.#settleAtlasProbe(true, probe),
812
+ );
813
+ }
814
+ }
815
+
816
+ #settleAtlasProbe(accepted: boolean, probe: { readonly destroy?: () => void } | undefined): void {
817
+ probe?.destroy?.();
818
+ this.#atlasMode = accepted ? "render3d" : "copy";
819
+ this.#gpuWarmupSettled = true;
820
+ }
821
+
711
822
  #ensureGpuResources(): void {
712
823
  if (this.#cubeRenderTarget !== undefined) return;
824
+ const atlasMode = this.#atlasMode;
825
+ if (atlasMode === undefined) return;
713
826
  this.#cubeRenderTarget = new CubeRenderTarget(this.#cubemapSize, {
714
827
  depthBuffer: true,
715
828
  generateMipmaps: false,
@@ -732,15 +845,31 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
732
845
  minFilter: NearestFilter,
733
846
  type: FloatType,
734
847
  });
735
- this.#atlasTarget = new RenderTarget3D(this.resolution.x, this.resolution.y, this.#atlasDepth, {
736
- depthBuffer: false,
737
- generateMipmaps: false,
738
- magFilter: LinearFilter,
739
- minFilter: LinearFilter,
740
- type: FloatType,
741
- });
742
- this.#atlasTexture = this.#atlasTarget.texture as Data3DTexture;
743
- this.#atlasTexture.format = RGBAFormat;
848
+ if (atlasMode === "render3d") {
849
+ this.#atlasTarget = new RenderTarget3D(
850
+ this.resolution.x,
851
+ this.resolution.y,
852
+ this.#atlasDepth,
853
+ {
854
+ depthBuffer: false,
855
+ generateMipmaps: false,
856
+ magFilter: LinearFilter,
857
+ minFilter: LinearFilter,
858
+ type: FloatType,
859
+ },
860
+ );
861
+ this.#atlasTexture = this.#atlasTarget.texture as Data3DTexture;
862
+ this.#atlasTexture.format = RGBAFormat;
863
+ } else {
864
+ // The atlas stays the plain 3D texture made at construction; slices are rendered here and copied in.
865
+ this.#sliceTarget = new RenderTarget(this.resolution.x, this.resolution.y, {
866
+ depthBuffer: false,
867
+ generateMipmaps: false,
868
+ magFilter: NearestFilter,
869
+ minFilter: NearestFilter,
870
+ type: FloatType,
871
+ });
872
+ }
744
873
  this.#setSamplingIsolated(this.#samplingIsolated);
745
874
  this.#quadCamera = new OrthographicCamera(-1, 1, 1, -1, 0, 1);
746
875
  this.#quadMesh = new Mesh(new PlaneGeometry(2, 2));
@@ -762,7 +891,7 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
762
891
  if (this.#gpuWarmupStarted) return;
763
892
  const projectionTarget = this.#projectionTarget;
764
893
  const projectionMaterial = this.#projectionMaterial;
765
- const atlasTarget = this.#atlasTarget;
894
+ const atlasTarget = this.#atlasTarget ?? this.#sliceTarget;
766
895
  const repackMaterials = this.#repackMaterials;
767
896
  if (
768
897
  projectionTarget === undefined ||
@@ -775,7 +904,11 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
775
904
  // First-use shader work belongs to scene entry, before bounded bake slices are presented.
776
905
  this.#renderQuad(projectionTarget, projectionMaterial);
777
906
  repackMaterials.forEach((material, index) => {
778
- this.#renderQuad(atlasTarget, material, index * this.paddedSlices);
907
+ this.#renderQuad(
908
+ atlasTarget,
909
+ material,
910
+ this.#atlasTarget === undefined ? undefined : index * this.paddedSlices,
911
+ );
779
912
  });
780
913
  }
781
914
 
@@ -969,7 +1102,7 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
969
1102
  }
970
1103
 
971
1104
  #repackSliceToAtlas(repackIndex: number): void {
972
- const atlasTarget = this.#atlasTarget;
1105
+ const atlasTarget = this.#atlasTarget ?? this.#sliceTarget;
973
1106
  const materials = this.#repackMaterials;
974
1107
  if (atlasTarget === undefined || materials === undefined) {
975
1108
  throw new Error("ProbeVolume repack resources were not initialized.");
@@ -980,10 +1113,35 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
980
1113
  this.#repackSlice.value = sourceSlice;
981
1114
  atlasTarget.viewport.set(0, 0, this.resolution.x, this.resolution.y);
982
1115
  atlasTarget.scissorTest = false;
983
- this.#renderQuad(
984
- atlasTarget,
985
- valueAt(materials, subVolume, "repack material"),
986
- subVolume * this.paddedSlices + localSlice,
1116
+ const material = valueAt(materials, subVolume, "repack material");
1117
+ const atlasSlice = subVolume * this.paddedSlices + localSlice;
1118
+ if (this.#atlasTarget !== undefined) {
1119
+ this.#renderQuad(atlasTarget, material, atlasSlice);
1120
+ return;
1121
+ }
1122
+ this.#renderQuad(atlasTarget, material);
1123
+ this.#copySliceToAtlas(atlasSlice);
1124
+ }
1125
+
1126
+ /** The atlas path for a device with no 3D render attachment: the 2D slice target joins the 3D atlas. */
1127
+ #copySliceToAtlas(atlasSlice: number): void {
1128
+ const raw = this.#rawRenderer();
1129
+ const source = this.#sliceTarget;
1130
+ if (source === undefined || raw.copyTextureToTexture === undefined) {
1131
+ throw new Error(
1132
+ "ProbeVolume requires WebGPU texture-to-texture copies for its atlas slices.",
1133
+ );
1134
+ }
1135
+ if (!this.#atlasUploaded) {
1136
+ // The copy needs the GPU atlas to exist; its first upload is the zero-filled CPU atlas.
1137
+ raw.initTexture?.(this.#atlasTexture);
1138
+ this.#atlasUploaded = true;
1139
+ }
1140
+ raw.copyTextureToTexture(
1141
+ source.texture,
1142
+ this.#atlasTexture,
1143
+ new Box2(new Vector2(0, 0), new Vector2(this.resolution.x, this.resolution.y)),
1144
+ new Vector3(0, 0, atlasSlice),
987
1145
  );
988
1146
  }
989
1147
 
@@ -1048,7 +1206,9 @@ export class ProbeVolume extends Object3D implements IComputeDriven {
1048
1206
  #clearPreviousBake(): void {
1049
1207
  this.#coefficients.fill(0);
1050
1208
  this.#atlasData.fill(0);
1051
- if (this.#atlasTarget === undefined) this.#atlasTexture.needsUpdate = true;
1209
+ if (this.#atlasTarget === undefined && this.#sliceTarget === undefined) {
1210
+ this.#atlasTexture.needsUpdate = true;
1211
+ }
1052
1212
  }
1053
1213
 
1054
1214
  #setSamplingIsolated(isolated: boolean): void {
@@ -0,0 +1,177 @@
1
+ import type { Light, Material, Mesh, Object3D } from "three";
2
+ import {
3
+ clamp,
4
+ diffuseColor,
5
+ metalness,
6
+ normalView,
7
+ positionViewDirection,
8
+ roughness,
9
+ uniform,
10
+ vec3,
11
+ } from "three/tsl";
12
+ import { MeshPhysicalNodeMaterial, MeshStandardNodeMaterial, type Node } from "three/webgpu";
13
+
14
+ declare module "three" {
15
+ // quality-allow: declaration merging needs three's own interface name, and the naming rule would demand an I prefix
16
+ // biome-ignore lint/style/useNamingConvention: a module augmentation keeps three's own class name.
17
+ interface Material {
18
+ /**
19
+ * Unreal's Substrate rough diffuse, the EON model (PRD-653): direct light shades the diffuse lobe of a
20
+ * standard or physical material with EON where three shades Lambert. The default is off. Indirect light
21
+ * stays Lambert, and a material changed after its first draw needs `needsUpdate`.
22
+ */
23
+ roughDiffuse?: boolean;
24
+ }
25
+ // quality-allow: declaration merging needs three's own interface name, and the naming rule would demand an I prefix
26
+ // biome-ignore lint/style/useNamingConvention: a module augmentation keeps three's own class name.
27
+ interface PointLight {
28
+ /** Unreal's Source Radius in metres: how large the lamp is. A rough diffuse surface blends back to Lambert at 20 cm. */
29
+ sourceRadius?: number;
30
+ }
31
+ // quality-allow: declaration merging needs three's own interface name, and the naming rule would demand an I prefix
32
+ // biome-ignore lint/style/useNamingConvention: a module augmentation keeps three's own class name.
33
+ interface SpotLight {
34
+ /** Unreal's Source Radius in metres, as on PointLight. */
35
+ sourceRadius?: number;
36
+ }
37
+ }
38
+
39
+ /** Diffuse_GGX_Rough (Engine/Shaders/Private/BRDF.ush): EON's roughness is 0.4 x the material's. */
40
+ const ROUGHNESS_SCALE = 0.4;
41
+ /** The same function weights EON by the lamp's size: a lamp of 20 cm or more is shaded as Lambert. */
42
+ const SIZE_LIMIT = 0.2;
43
+ /** The EON model's fit constants (Portsmouth, Kutz and Hill), the ones the native engine's standard program holds too. */
44
+ const SINGLE_LOSS = 1 - 1 / (1 + (0.5 - 2 / (3 * Math.PI)));
45
+ const MULTI_TILT = 0.262048;
46
+ const ALBEDO_GAIN = 0.189468;
47
+ const EPSILON = 1e-6;
48
+
49
+ type Lamp = Light & { readonly isDirectionalLight?: boolean; readonly sourceRadius?: number };
50
+
51
+ /** The lighting model's `direct`, as far as this module drives it. */
52
+ interface IDirectInput {
53
+ readonly lightDirection: Node<"vec3">;
54
+ readonly lightNode?: { readonly light?: Lamp };
55
+ readonly reflectedLight: { readonly directDiffuse: Node<"vec3"> };
56
+ }
57
+ interface ILightingModel {
58
+ direct(input: IDirectInput, builder: unknown): void;
59
+ }
60
+ interface IPatchable {
61
+ setupLightingModel?: (this: Material, builder: unknown) => ILightingModel;
62
+ }
63
+
64
+ const sourceRadii = new WeakMap<object, Node<"float">>();
65
+ const installed = new WeakSet<object>();
66
+
67
+ /** Undefined for a sun, else `1 - sourceRadius / 20 cm` held in 0..1; the radius is read each render. */
68
+ function lampWeight(light: Lamp | undefined): Node<"float"> | undefined {
69
+ if (light === undefined || light.isDirectionalLight === true) return undefined;
70
+ let radius = sourceRadii.get(light);
71
+ if (radius === undefined) {
72
+ radius = uniform(0).onRenderUpdate(() => light.sourceRadius ?? 0) as Node<"float">;
73
+ sourceRadii.set(light, radius);
74
+ }
75
+ return clamp(radius.mul(1 / SIZE_LIMIT).oneMinus()) as Node<"float">;
76
+ }
77
+
78
+ /**
79
+ * EON's factor on Lambert for one light, so `albedo / pi * factor` is the EON BRDF (Portsmouth, Kutz and Hill). It is 1 at
80
+ * r = 0, and it never divides by the albedo, so black stays black. The native engine's standard program holds the same
81
+ * arithmetic (`roughDiffuseFactor` in shader/standard.cpp); `conformance/registry.json` keeps the two equal.
82
+ */
83
+ function roughDiffuseFactor(
84
+ albedo: Node<"vec3">,
85
+ r: Node<"float">,
86
+ nov: Node<"float">,
87
+ nol: Node<"float">,
88
+ vol: Node<"float">,
89
+ ): Node<"vec3"> {
90
+ const s = vol.sub(nov.mul(nol));
91
+ const sOverT = s.div(nov.max(nol).max(EPSILON)).max(s);
92
+ const single = r.mul(SINGLE_LOSS).oneMinus();
93
+ const front = single.mul(r.mul(sOverT).add(1));
94
+ const multi = single.mul(r.mul(MULTI_TILT).mul(nov.oneMinus()).add(1)).oneMinus();
95
+ const gain = albedo.oneMinus().mul(ALBEDO_GAIN).mul(r).add(1);
96
+ return gain.mul(front.add(albedo.mul(gain).mul(multi))) as Node<"vec3">;
97
+ }
98
+
99
+ /**
100
+ * Turns a stock lighting model's Lambert diffuse into EON. The model adds irradiance x Lambert to `directDiffuse`; that term
101
+ * goes into a scratch variable here and returns scaled by EON's factor, so whatever else the model multiplies it by (sheen's
102
+ * energy compensation) stays in, and the specular and clearcoat terms are untouched.
103
+ */
104
+ function roughen(model: ILightingModel): ILightingModel {
105
+ const lambert = model.direct;
106
+ model.direct = function direct(
107
+ this: ILightingModel,
108
+ input: IDirectInput,
109
+ builder: unknown,
110
+ ): void {
111
+ const scratch = vec3(0).toVar() as Node<"vec3">;
112
+ lambert.call(
113
+ this,
114
+ { ...input, reflectedLight: { ...input.reflectedLight, directDiffuse: scratch } },
115
+ builder,
116
+ );
117
+ const nov = clamp(normalView.dot(positionViewDirection)) as Node<"float">;
118
+ const nol = clamp(normalView.dot(input.lightDirection)) as Node<"float">;
119
+ const vol = positionViewDirection.dot(input.lightDirection) as Node<"float">;
120
+ let r = roughness.mul(ROUGHNESS_SCALE) as Node<"float">;
121
+ const weight = lampWeight(input.lightNode?.light);
122
+ if (weight !== undefined) r = r.mul(weight) as Node<"float">;
123
+ // three's diffuseContribution, which three/tsl does not export: the colour less its metal share.
124
+ const albedo = diffuseColor.rgb.mul(metalness.oneMinus()) as Node<"vec3">;
125
+ const factor = roughDiffuseFactor(albedo, r, nov, nol, vol);
126
+ (
127
+ input.reflectedLight.directDiffuse as Node<"vec3"> & { addAssign(value: Node): void }
128
+ ).addAssign(scratch.mul(factor));
129
+ };
130
+ return model;
131
+ }
132
+
133
+ /**
134
+ * Hooks `setupLightingModel` of three's standard and physical node materials once, so a material with `roughDiffuse` set
135
+ * shades its direct diffuse with EON. A material without it gets three's own model back untouched. Idempotent. Call
136
+ * {@link useRoughDiffuse} to mark the materials as well.
137
+ */
138
+ export function installRoughDiffuse(): void {
139
+ for (const material of [MeshStandardNodeMaterial, MeshPhysicalNodeMaterial]) {
140
+ // quality-allow: three's setupLightingModel types its direct input as LightingModelDirectInput, which IDirectInput narrows to the fields read here
141
+ const proto = material?.prototype as unknown as IPatchable | undefined;
142
+ const original = proto?.setupLightingModel;
143
+ if (proto === undefined || original === undefined || installed.has(proto)) continue;
144
+ installed.add(proto);
145
+ proto.setupLightingModel = function setupLightingModel(this: Material, builder: unknown) {
146
+ const model = original.call(this, builder);
147
+ return this.roughDiffuse === true ? roughen(model) : model;
148
+ };
149
+ }
150
+ }
151
+
152
+ /** The Node variants set no `isMeshStandardMaterial`, so the type name is the one test that covers three and the owned engine. */
153
+ const STANDARD = /^Mesh(?:Standard|Physical)(?:Node)?Material$/u;
154
+
155
+ function isStandard(material: unknown): material is Material {
156
+ return STANDARD.test((material as { type?: string } | null)?.type ?? "");
157
+ }
158
+
159
+ /**
160
+ * Shades every standard and physical material under `root` the way Unreal's Substrate does a rough surface: direct light
161
+ * meets the diffuse lobe with the EON model, not Lambert. Returns how many materials changed. `enabled: false` puts Lambert
162
+ * back. The owned engine reads `material.roughDiffuse` itself; on three's own WebGPU renderer this also installs the hook.
163
+ */
164
+ export function useRoughDiffuse(root: Object3D, enabled = true): number {
165
+ installRoughDiffuse();
166
+ let changed = 0;
167
+ root.traverse((object) => {
168
+ const material = (object as Partial<Mesh>).material;
169
+ for (const each of Array.isArray(material) ? material : [material]) {
170
+ if (!isStandard(each) || (each.roughDiffuse === true) === enabled) continue;
171
+ each.roughDiffuse = enabled;
172
+ each.needsUpdate = true;
173
+ changed++;
174
+ }
175
+ });
176
+ return changed;
177
+ }