@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
@@ -0,0 +1,607 @@
1
+ import {
2
+ type CubeTexture,
3
+ type DepthTexture,
4
+ GreaterEqualCompare,
5
+ LessEqualCompare,
6
+ type LightShadow,
7
+ type OrthographicCamera,
8
+ type PerspectiveCamera,
9
+ } from "three";
10
+ import {
11
+ Fn,
12
+ If,
13
+ cameraPosition,
14
+ cross,
15
+ cubeTexture,
16
+ dFdx,
17
+ dFdy,
18
+ float,
19
+ ivec2,
20
+ max,
21
+ min,
22
+ positionWorld,
23
+ reference,
24
+ sqrt,
25
+ step,
26
+ type texture,
27
+ textureLoad,
28
+ uniform,
29
+ vec2,
30
+ vec3,
31
+ } from "three/tsl";
32
+ import type { Node } from "three/webgpu";
33
+
34
+ /** tan(5 degrees): Unreal's `r.Shadow.Virtual.SubsurfaceShadowMinSourceAngle`, the sun's least source on a leaf. */
35
+ export const LEAF_MIN_SOURCE_TANGENT = Math.tan((5 * Math.PI) / 180);
36
+
37
+ declare module "three" {
38
+ // quality-allow: declaration merging needs three's own interface name, and the naming rule would demand an I prefix
39
+ // biome-ignore lint/style/useNamingConvention: a module augmentation keeps three's own class name.
40
+ interface Material {
41
+ /**
42
+ * Unreal's Two Sided Foliage shading model (PRD-651). The receiver looks its shadow up where it
43
+ * stands, without the normal bias, and sees a sun of at least 5 degrees. The default is off: a
44
+ * card with two sides and a cut is a default lit material in Unreal, and keeps the normal bias.
45
+ */
46
+ twoSidedFoliage?: boolean;
47
+ }
48
+ }
49
+
50
+ /**
51
+ * A receiver marked `twoSidedFoliage` (PRD-651). Unreal gives its Two Sided Foliage and subsurface
52
+ * pixels no normal bias and a sun source of at least 5 degrees, because a thin leaf biased along its
53
+ * normal either shades itself or lets light through. The sides and the cut do not choose this: Unreal
54
+ * reads the shading model, so the rule reads the marker and never infers it.
55
+ */
56
+ export function isLeafReceiver(
57
+ material: { readonly twoSidedFoliage?: boolean } | null | undefined,
58
+ ): boolean {
59
+ return material?.twoSidedFoliage === true;
60
+ }
61
+
62
+ /** The tangent of the source angle a receiver sees: a leaf receiver sees at least 5 degrees. */
63
+ export function receiverSourceTangent(
64
+ material: Parameters<typeof isLeafReceiver>[0],
65
+ tangent: number,
66
+ ): number {
67
+ return isLeafReceiver(material) ? Math.max(tangent, LEAF_MIN_SOURCE_TANGENT) : tangent;
68
+ }
69
+
70
+ /** World-space gap to UV radius; sourceAngleRad is in radians, in [0, PI/2). */
71
+ export function penumbraUv(
72
+ gapMetres: number,
73
+ sourceAngleRad: number,
74
+ frustumWidthMetres: number,
75
+ mapSize: number,
76
+ ): number {
77
+ for (const [name, value] of Object.entries({
78
+ gapMetres,
79
+ sourceAngleRad,
80
+ frustumWidthMetres,
81
+ mapSize,
82
+ })) {
83
+ if (!Number.isFinite(value) || value < 0)
84
+ throw new RangeError(`${name} must be finite and non-negative`);
85
+ }
86
+ if (sourceAngleRad >= Math.PI / 2 || frustumWidthMetres === 0 || mapSize === 0) {
87
+ throw new RangeError("angle must be < PI/2; frustum width and map size must be positive");
88
+ }
89
+ return Math.max(1 / mapSize, (gapMetres * Math.tan(sourceAngleRad)) / frustumWidthMetres);
90
+ }
91
+
92
+ /**
93
+ * The caster gap that Unreal's shadow-map ray test sees (PRD-634). Each ray runs `rayLengthScale` times the
94
+ * receiver's view distance toward the light, sampled `samplesPerRay` times at squared steps from a random
95
+ * start, far end first. It counts as blocked only when its first sample under the caster lies inside the
96
+ * caster's silhouette, so the edge spreads by that sample's distance and not by the caster's: this is that
97
+ * distance, averaged over the random start. 0 samples keeps the gap as it is.
98
+ * UE 5.8.3: Engine/Shaders/Private/VirtualShadowMaps/VirtualShadowMapSMRTTemplate.ush:41-130 (the sample
99
+ * times and the hit test), VirtualShadowMapProjectionDirectional.ush:230 (the ray length),
100
+ * Engine/Config/BaseScalability.ini:263 (4 samples per ray at Epic),
101
+ * Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapArray.cpp:760 (the 1.5 scale).
102
+ */
103
+ export function shadowRayOccluderGap(
104
+ gap: number,
105
+ viewDistance: number,
106
+ samplesPerRay: number,
107
+ rayLengthScale: number,
108
+ ): number {
109
+ if (samplesPerRay === 0) return gap;
110
+ const reach = rayLengthScale * viewDistance;
111
+ const x = reach > 0 ? Math.min(1, Math.sqrt(gap / reach)) : 1;
112
+ const n = samplesPerRay;
113
+ return reach * (x >= 1 / n ? x * x - x / n + 1 / (3 * n * n) : (n * x ** 3) / 3);
114
+ }
115
+
116
+ export interface ISourceAngleShadowOptions {
117
+ /** Required game-owned angular radius in radians, in [0, PI/2). No default. */
118
+ sourceAngleRad: number;
119
+ /** Fixed sample count, integer 1–64; default 16. Recreate the filter to change it. */
120
+ blockerSamples?: number;
121
+ /** Fixed sample count, integer 1–64; default 16. */
122
+ filterSamples?: number;
123
+ /**
124
+ * The receiver's own pixel, this many times over, blurs the edge on top of the source angle (the two add as
125
+ * the blur of two independent sources), so a contact edge is not a one-texel step that crawls as the camera
126
+ * moves. Unreal's sharpest sun-shadow edge is about a pixel wide (its texel dither and temporal resolve).
127
+ * Finite, in [0, 16]; default 0, which leaves the source angle alone.
128
+ */
129
+ minPenumbraPixels?: number;
130
+ /**
131
+ * Unreal's shadow-map ray samples (`r.Shadow.Virtual.SMRT.SamplesPerRayDirectional`, 4 at Epic): the edge
132
+ * spreads from the caster gap that the ray test sees (`shadowRayOccluderGap`). Integer 0–64; default 4.
133
+ * 0 is the override that spreads the edge by the full geometric gap.
134
+ */
135
+ samplesPerRay?: number;
136
+ /** The ray's length over the receiver's view distance (`r.Shadow.Virtual.SMRT.RayLengthScaleDirectional`); default 1.5. */
137
+ rayLengthScale?: number;
138
+ }
139
+
140
+ /** The object passed by three r185 ShadowNode.setupShadowFilter. */
141
+ export interface ISourceAngleShadowInputs {
142
+ depthTexture: DepthTexture;
143
+ shadowCoord: Node<"vec3">;
144
+ shadow: LightShadow;
145
+ depthLayer?: number;
146
+ }
147
+
148
+ /**
149
+ * Blocker search followed by variable-radius PCF for orthographic directional shadows.
150
+ * Camera bounds, zoom, near/far and mapSize are live references. Use a depth shadow map,
151
+ * not VSM. Both ordinary and reversed depth comparisons are supported.
152
+ * Ideas only: Unreal Engine/Shaders/Private/ShadowPercentageCloserFiltering.ush,
153
+ * DirectionalPCSS (blocker average and source-angle gap); independently written TSL.
154
+ */
155
+ export function sourceAngleShadowFilter({
156
+ sourceAngleRad,
157
+ blockerSamples = 16,
158
+ filterSamples = 16,
159
+ minPenumbraPixels = 0,
160
+ samplesPerRay = 4,
161
+ rayLengthScale = 1.5,
162
+ }: ISourceAngleShadowOptions): (inputs: ISourceAngleShadowInputs) => Node<"float"> {
163
+ penumbraUv(0, sourceAngleRad, 1, 1);
164
+ for (const count of [blockerSamples, filterSamples]) {
165
+ if (!Number.isInteger(count) || count < 1 || count > 64) {
166
+ throw new RangeError("shadow sample counts must be integers in [1, 64]");
167
+ }
168
+ }
169
+ if (!Number.isFinite(minPenumbraPixels) || minPenumbraPixels < 0 || minPenumbraPixels > 16)
170
+ throw new RangeError("minPenumbraPixels must be finite and in [0, 16]");
171
+ if (!Number.isInteger(samplesPerRay) || samplesPerRay < 0 || samplesPerRay > 64)
172
+ throw new RangeError("samplesPerRay must be an integer in [0, 64]");
173
+ if (!Number.isFinite(rayLengthScale) || rayLengthScale <= 0)
174
+ throw new RangeError("rayLengthScale must be finite and positive");
175
+ const tangent = Math.tan(sourceAngleRad);
176
+ const disk = (index: number, count: number) => {
177
+ const radius = Math.sqrt((index + 0.5) / count);
178
+ const angle = index * Math.PI * (3 - Math.sqrt(5));
179
+ return vec2(radius * Math.cos(angle), radius * Math.sin(angle));
180
+ };
181
+ const filter = ({
182
+ depthTexture,
183
+ shadowCoord,
184
+ shadow,
185
+ depthLayer = 0,
186
+ }: ISourceAngleShadowInputs) => {
187
+ const camera = shadow.camera as OrthographicCamera;
188
+ if (camera.isOrthographicCamera !== true) {
189
+ throw new RangeError("source-angle shadows require an orthographic shadow camera");
190
+ }
191
+ penumbraUv(0, sourceAngleRad, (camera.right - camera.left) / camera.zoom, shadow.mapSize.x);
192
+ penumbraUv(0, sourceAngleRad, (camera.top - camera.bottom) / camera.zoom, shadow.mapSize.y);
193
+ if (
194
+ !Number.isFinite(camera.near) ||
195
+ camera.near < 0 ||
196
+ !Number.isFinite(camera.far) ||
197
+ camera.far <= camera.near
198
+ ) {
199
+ throw new RangeError("shadow camera requires finite 0 <= near < far");
200
+ }
201
+ if (!Number.isFinite(camera.zoom) || camera.zoom <= 0)
202
+ throw new RangeError("shadow camera zoom must be positive and finite");
203
+ if (
204
+ depthTexture.compareFunction !== LessEqualCompare &&
205
+ depthTexture.compareFunction !== GreaterEqualCompare
206
+ )
207
+ throw new RangeError("source-angle shadows require a comparison depth texture, not VSM");
208
+ const reversed = depthTexture.compareFunction === GreaterEqualCompare;
209
+ const size = reference("mapSize", "vec2", shadow);
210
+ const near = reference("near", "float", camera);
211
+ const range = reference("far", "float", camera).sub(near);
212
+ const span = vec2(
213
+ reference("right", "float", camera).sub(reference("left", "float", camera)),
214
+ reference("top", "float", camera).sub(reference("bottom", "float", camera)),
215
+ ).div(reference("zoom", "float", camera));
216
+ const texel = vec2(1).div(size);
217
+ const isArray = "isArrayTexture" in depthTexture && depthTexture.isArrayTexture === true;
218
+ const withLayer = (sample: ReturnType<typeof texture>) =>
219
+ isArray ? sample.depth(float(depthLayer)) : sample;
220
+ const linearDepth = (depth: Node<"float">) => (reversed ? depth.oneMinus() : depth);
221
+ return Fn(
222
+ (_inputs: unknown, builder: { readonly material?: Parameters<typeof isLeafReceiver>[0] }) => {
223
+ // A receiver marked twoSidedFoliage sees the sun at 5 degrees at least; the node is built per material.
224
+ const reach = receiverSourceTangent(builder.material, tangent);
225
+ const receiver = linearDepth(shadowCoord.z);
226
+ // Near-plane distance bounds the largest possible caster/receiver gap.
227
+ const searchRadius = max(texel, vec2(receiver.mul(range).mul(reach)).div(span)).toVar();
228
+ const blockerSum = float(0).toVar();
229
+ const blockerCount = float(0).toVar();
230
+ // Integer loads read raw depth without interpolated blockers. Both loops load: three r185
231
+ // gives a depth texture one sampler binding, typed by the first node that registers it, so
232
+ // a load followed by `.compare()` emitted a plain sampler and failed to compile.
233
+ const load = (uv: Node<"vec2">) =>
234
+ linearDepth(
235
+ withLayer(
236
+ textureLoad(
237
+ depthTexture,
238
+ ivec2(min(max(uv.mul(size).floor(), vec2(0)), size.sub(1))),
239
+ ),
240
+ ).r,
241
+ );
242
+ for (let index = 0; index < blockerSamples; index++) {
243
+ const depth = load(
244
+ shadowCoord.xy.add(disk(index, blockerSamples).mul(searchRadius)),
245
+ ).toVar();
246
+ If(depth.lessThan(receiver), () => {
247
+ blockerSum.addAssign(depth);
248
+ blockerCount.addAssign(1);
249
+ });
250
+ }
251
+ const blockerGap = max(0, receiver.sub(blockerSum.div(max(blockerCount, 1)))).mul(range);
252
+ // shadowRayOccluderGap, per receiver.
253
+ const n = samplesPerRay;
254
+ const rayReach = positionWorld.distance(cameraPosition).mul(rayLengthScale);
255
+ const x = min(1, sqrt(blockerGap.div(max(rayReach, 1e-6))));
256
+ const gap =
257
+ n === 0
258
+ ? blockerGap
259
+ : rayReach.mul(
260
+ x.greaterThanEqual(1 / n).select(
261
+ x
262
+ .mul(x)
263
+ .sub(x.div(n))
264
+ .add(1 / (3 * n * n)),
265
+ x
266
+ .mul(x)
267
+ .mul(x)
268
+ .mul(n / 3),
269
+ ),
270
+ );
271
+ const penumbra = vec2(gap.mul(reach)).div(span);
272
+ // The receiver's pixel in this map's uv, per axis (the length of its two screen steps together), as
273
+ // many times as `minPenumbraPixels` asks for, and at most 16 texels: the steps of a quad that straddles
274
+ // a silhouette are the distance between two surfaces.
275
+ const stepX = dFdx(shadowCoord.xy);
276
+ const stepY = dFdy(shadowCoord.xy);
277
+ const pixels = min(
278
+ sqrt(stepX.mul(stepX).add(stepY.mul(stepY))).mul(minPenumbraPixels),
279
+ texel.mul(16),
280
+ );
281
+ const radius = max(
282
+ texel,
283
+ minPenumbraPixels === 0 ? penumbra : sqrt(penumbra.mul(penumbra).add(pixels.mul(pixels))),
284
+ ).toVar();
285
+ const visibility = float(0).toVar();
286
+ for (let index = 0; index < filterSamples; index++) {
287
+ const depth = load(shadowCoord.xy.add(disk(index, filterSamples).mul(radius)));
288
+ visibility.addAssign(step(receiver, depth));
289
+ }
290
+ return blockerCount.greaterThan(0).select(visibility.div(filterSamples), float(1));
291
+ },
292
+ )();
293
+ };
294
+ // Native virtual maps translate the same filter parameters into atlas-aware depth loads.
295
+ return Object.assign(filter, {
296
+ [Symbol.for("threenative.sourceAngleShadowFilter")]: Object.freeze({
297
+ sourceAngleRad,
298
+ blockerSamples,
299
+ filterSamples,
300
+ minPenumbraPixels,
301
+ samplesPerRay,
302
+ rayLengthScale,
303
+ }),
304
+ });
305
+ }
306
+
307
+ /**
308
+ * A lamp's penumbra radius in tangent units (offset over distance) at the receiver: the disk of
309
+ * `sourceRadius` metres seen past a blocker at `blockerDistance` from a receiver at `receiverDistance`.
310
+ * Times the receiver distance it is the penumbra's world radius, linear in the caster gap and the radius.
311
+ */
312
+ export function lampPenumbraTangent(
313
+ sourceRadius: number,
314
+ blockerDistance: number,
315
+ receiverDistance: number,
316
+ ): number {
317
+ if (!Number.isFinite(sourceRadius) || sourceRadius < 0)
318
+ throw new RangeError("sourceRadius must be finite and non-negative");
319
+ if (!(blockerDistance > 0) || !(receiverDistance > 0) || !Number.isFinite(receiverDistance))
320
+ throw new RangeError("blocker and receiver distances must be positive and finite");
321
+ return sourceRadius * Math.max(0, 1 / blockerDistance - 1 / receiverDistance);
322
+ }
323
+
324
+ export interface ISourceRadiusShadowOptions {
325
+ /** Required game-owned lamp radius in metres (Unreal's SourceRadius); 0 is one hard tap. */
326
+ sourceRadius: number;
327
+ /** Fixed sample count, integer 1–64; default 16. Recreate the filter to change it. */
328
+ blockerSamples?: number;
329
+ /** Fixed sample count, integer 1–64; default 16. */
330
+ filterSamples?: number;
331
+ /**
332
+ * The share of the geometric penumbra the lamp keeps, in (0, 4]; default `LAMP_PENUMBRA_SCALE`.
333
+ * 1 is the width a disk lamp throws; Unreal's shadow-map ray test samples each ray a few times and
334
+ * resolves about 0.6 of it at its Epic counts.
335
+ */
336
+ penumbraScale?: number;
337
+ }
338
+
339
+ /**
340
+ * The default `penumbraScale`. Unreal 5.8.3's local-light ray test (8 rays, 4 samples each at Epic) misses
341
+ * the thin end of a penumbra: measured against a geometric disk lamp it keeps 0.47 to 0.69 of the width on
342
+ * the calibration scenes (`lamp-room`, `cornell`), and a simulation of the test at those counts averages 0.6.
343
+ */
344
+ export const LAMP_PENUMBRA_SCALE = 0.6;
345
+
346
+ /** A spot light's filter inputs (ShadowNode), or a point light's (PointShadowNode: `bd3D`, `dp`). */
347
+ export interface ISourceRadiusShadowInputs extends ISourceAngleShadowInputs {
348
+ bd3D?: Node<"vec3">;
349
+ dp?: Node<"float">;
350
+ }
351
+
352
+ /**
353
+ * Blocker search followed by variable-radius PCF for a spot light's map or a point light's cube: the
354
+ * penumbra is `penumbraScale * lampPenumbraTangent` at the average blocker that shades the receiver, at
355
+ * least half a texel. The search runs `blockerPasses` times: the nearest blocker in a cone has the widest
356
+ * penumbra and every blocker that shades the receiver lies inside it, so the cone shrinks to that penumbra;
357
+ * the last cone averages only the blockers whose own penumbra reaches the receiver, so a volume's far
358
+ * faces, a wall's own texels and a nearer object off to the side never pull the width. A texel is a blocker
359
+ * only when it is nearer than the receiver's own plane (read from the screen derivatives), so a tilted wall
360
+ * that the lamp sees nearer on one side never shades itself, and the filter compares each tap against
361
+ * that plane too. The receiver's own ray is a tap of every cone and always counts when it is blocked, since
362
+ * it lies inside the lamp's disk: a back-face map stores a box's far face within centimetres of the floor
363
+ * behind it, and a thin rod falls between the taps. A receiver no blocker reaches is lit. Distances are
364
+ * along the receiver's ray, so a cube's faces agree: a face stores the depth along its own axis.
365
+ * The spot map reads raw depth like `sourceAngleShadowFilter`. A cube has no integer load in WGSL and
366
+ * three r185 gives a depth texture one sampler, so the point light's search compares each tap at four
367
+ * depths between the light and the plane and takes the blocker from the step where it turns dark.
368
+ * Ideas only: Unreal VirtualShadowMapProjectionSpot.ush (rays in a cone of SourceRadius / distance);
369
+ * independently written TSL. The owned engine reads the cube's raw depths instead.
370
+ */
371
+ export function sourceRadiusShadowFilter({
372
+ sourceRadius,
373
+ blockerSamples = 16,
374
+ filterSamples = 16,
375
+ penumbraScale = LAMP_PENUMBRA_SCALE,
376
+ }: ISourceRadiusShadowOptions): (inputs: ISourceRadiusShadowInputs) => Node<"float"> {
377
+ lampPenumbraTangent(sourceRadius, 1, 1);
378
+ if (!Number.isFinite(penumbraScale) || penumbraScale <= 0 || penumbraScale > 4)
379
+ throw new RangeError("penumbraScale must be in (0, 4]");
380
+ for (const count of [blockerSamples, filterSamples]) {
381
+ if (!Number.isInteger(count) || count < 1 || count > 64) {
382
+ throw new RangeError("shadow sample counts must be integers in [1, 64]");
383
+ }
384
+ }
385
+ const levels = 4;
386
+ // ponytail: two passes, as on the owned engine; a third moved the edge by under 3 % in the wall test.
387
+ const blockerPasses = 2;
388
+ const disk = (index: number, count: number) => {
389
+ const radius = Math.sqrt((index + 0.5) / count);
390
+ const angle = index * Math.PI * (3 - Math.sqrt(5));
391
+ return vec2(radius * Math.cos(angle), radius * Math.sin(angle));
392
+ };
393
+ const filter = ({ depthTexture, shadowCoord, shadow, bd3D, dp }: ISourceRadiusShadowInputs) => {
394
+ const camera = shadow.camera as PerspectiveCamera;
395
+ if (camera.isPerspectiveCamera !== true)
396
+ throw new RangeError(
397
+ "source-radius shadows require a spot or point light's perspective camera",
398
+ );
399
+ if (depthTexture.compareFunction !== LessEqualCompare)
400
+ throw new RangeError("source-radius shadows require a forward-depth comparison texture");
401
+ const near = reference("near", "float", camera);
402
+ const far = reference("far", "float", camera);
403
+ const size = reference("mapSize", "vec2", shadow).x;
404
+ // A [0, 1] perspective depth and its view depth.
405
+ const distanceOf = (depth: Node<"float">) =>
406
+ near.mul(far).div(far.sub(depth.mul(far.sub(near))));
407
+ const depthOf = (distance: Node<"float">) =>
408
+ far.mul(distance.sub(near)).div(distance.mul(far.sub(near)));
409
+ const radius = float(sourceRadius);
410
+ // The lamp's disk seen past a blocker, in tangent units: the penumbra's radius at the receiver.
411
+ const spreadOf = (blocker: Node<"float">, receiver: Node<"float">) =>
412
+ radius.mul(max(0, float(1).div(blocker).sub(float(1).div(receiver))));
413
+ const penumbraOf = (blocker: Node<"float">, receiver: Node<"float">, texel: Node<"float">) =>
414
+ sourceRadius === 0
415
+ ? float(0)
416
+ : max(texel.mul(0.5), spreadOf(blocker, receiver).mul(penumbraScale));
417
+ // ponytail: the search cone is cut at 0.5 tangent (27 degrees), as on the owned engine.
418
+ const searchOf = (receiver: Node<"float">) => min(0.5, spreadOf(near, receiver));
419
+ // d(distance) / d(tap offset): the 2x2 solve of the distance's screen derivatives against those of
420
+ // the tap coordinates. Called in uniform control flow, before any branch.
421
+ const slopeOf = (
422
+ jx: Node<"vec2">,
423
+ jy: Node<"vec2">,
424
+ distance: Node<"float">,
425
+ scale: Node<"float">,
426
+ ) => {
427
+ const [rx, ry] = [dFdx(distance), dFdy(distance)];
428
+ const det = jx.x.mul(jy.y).sub(jx.y.mul(jy.x));
429
+ const flat = det.abs().lessThan(1e-12);
430
+ const safe = flat.select(float(1), det);
431
+ return vec2(
432
+ rx.mul(jy.y).sub(jx.y.mul(ry)).div(safe),
433
+ jx.x.mul(ry).sub(jy.x.mul(rx)).div(safe),
434
+ )
435
+ .mul(flat.select(float(0), scale))
436
+ .toVar();
437
+ };
438
+ if (bd3D && dp) {
439
+ const absDir = bd3D.abs();
440
+ const tangent = cross(
441
+ bd3D,
442
+ absDir.x.greaterThan(absDir.z).select(vec3(0, 1, 0), vec3(1, 0, 0)),
443
+ ).normalize();
444
+ const bitangent = cross(bd3D, tangent);
445
+ // A depth compare answers a float; three's types call every texture read a vec4.
446
+ const tap = (offset: Node<"vec2">, reference: Node<"float">) =>
447
+ cubeTexture(
448
+ // quality-allow: the depth texture is a cube map the point-light shadow pass renders into, which three types as a plain DepthTexture
449
+ depthTexture as unknown as CubeTexture,
450
+ bd3D.add(tangent.mul(offset.x).add(bitangent.mul(offset.y))),
451
+ ).compare(reference) as unknown as Node<"float">; // quality-allow: a depth compare answers a float, and three 0.185 types every texture read as a vec4
452
+ // The depth along a tap's cube face over the distance along its ray: the ray's largest component
453
+ // over its length.
454
+ const axialPerEuclid = (offset: Node<"vec2">) => {
455
+ const ray = bd3D.add(tangent.mul(offset.x).add(bitangent.mul(offset.y))).abs();
456
+ return max(max(ray.x, ray.y), ray.z).div(
457
+ bd3D.add(tangent.mul(offset.x).add(bitangent.mul(offset.y))).length(),
458
+ );
459
+ };
460
+ return Fn(() => {
461
+ const receiver = distanceOf(dp)
462
+ .div(axialPerEuclid(vec2(0, 0)))
463
+ .toVar();
464
+ const slope = slopeOf(
465
+ vec2(dFdx(bd3D).dot(tangent), dFdx(bd3D).dot(bitangent)),
466
+ vec2(dFdy(bd3D).dot(tangent), dFdy(bd3D).dot(bitangent)),
467
+ receiver,
468
+ float(1),
469
+ );
470
+ // The receiver's plane at a tap offset as a distance along the tap's ray, and as the depth along its face.
471
+ const planeDistance = (offset: Node<"vec2">) =>
472
+ max(0, receiver.add(slope.x.mul(offset.x)).add(slope.y.mul(offset.y)));
473
+ const planeAxial = (offset: Node<"vec2">) =>
474
+ max(planeDistance(offset).mul(axialPerEuclid(offset)), near);
475
+ const visibility = float(1).toVar();
476
+ const cone = searchOf(receiver).toVar();
477
+ // One search cone: how many blockers, their summed distance, and the nearest. The last cone counts only
478
+ // the texels whose own penumbra reaches the receiver, and the receiver's own ray, which is inside the
479
+ // lamp's disk whatever the blocker's reach.
480
+ const blockerAt = (offset: Node<"vec2">) => {
481
+ const plane = planeAxial(offset);
482
+ const blocked = tap(offset, depthOf(plane)).oneMinus().toVar();
483
+ // Darker at more of the levels: the blocker is nearer the light.
484
+ let steps: Node<"float"> = float(0);
485
+ for (let level = 1; level <= levels; level++)
486
+ steps = steps.add(tap(offset, depthOf(plane.mul(level / (levels + 1)))).oneMinus());
487
+ const blocker = plane
488
+ .mul(float(levels + 0.5).sub(steps))
489
+ .div(levels + 1)
490
+ .div(axialPerEuclid(offset));
491
+ return { blocked, blocker };
492
+ };
493
+ const search = (last: boolean) => {
494
+ const sum = float(0).toVar();
495
+ const count = float(0).toVar();
496
+ const nearest = float(1e30).toVar();
497
+ const visit = (offset: Node<"vec2">, own: boolean) => {
498
+ const { blocked, blocker } = blockerAt(offset);
499
+ const reaches = offset.length().lessThanEqual(spreadOf(blocker, planeDistance(offset)));
500
+ const weight = last && !own ? reaches.select(blocked, float(0)) : blocked;
501
+ sum.addAssign(weight.mul(blocker));
502
+ count.addAssign(weight);
503
+ nearest.assign(blocked.greaterThan(0.5).select(min(nearest, blocker), nearest));
504
+ };
505
+ visit(vec2(0, 0), true);
506
+ for (let tapIndex = 0; tapIndex < blockerSamples; tapIndex++)
507
+ visit(disk(tapIndex, blockerSamples).mul(cone), false);
508
+ return { sum, count, nearest };
509
+ };
510
+ const pass = (index: number) => {
511
+ const last = index + 1 === blockerPasses;
512
+ const { sum, count, nearest } = search(last);
513
+ If(count.greaterThan(0), () => {
514
+ if (!last) {
515
+ cone.assign(min(cone, spreadOf(nearest, receiver)));
516
+ pass(index + 1);
517
+ return;
518
+ }
519
+ const blocker = sum.div(count);
520
+ const penumbra = penumbraOf(blocker, receiver, float(2).div(size)).toVar();
521
+ let lit: Node<"float"> = float(0);
522
+ for (let tapIndex = 0; tapIndex < filterSamples; tapIndex++) {
523
+ const offset = disk(tapIndex, filterSamples).mul(penumbra);
524
+ lit = lit.add(tap(offset, depthOf(planeAxial(offset))));
525
+ }
526
+ visibility.assign(lit.div(filterSamples));
527
+ });
528
+ };
529
+ pass(0);
530
+ return visibility;
531
+ })();
532
+ }
533
+ const tanHalf = uniform(1).onRenderUpdate(
534
+ () => Math.tan((camera.fov * Math.PI) / 360) / camera.zoom,
535
+ );
536
+ const uvPerTangent = float(0.5).div(tanHalf);
537
+ const sizes = vec2(size);
538
+ const load = (uv: Node<"vec2">) =>
539
+ textureLoad(depthTexture, ivec2(min(max(uv.mul(sizes).floor(), vec2(0)), sizes.sub(1)))).r;
540
+ return Fn(() => {
541
+ const receiver = distanceOf(shadowCoord.z).toVar();
542
+ const slope = slopeOf(dFdx(shadowCoord.xy), dFdy(shadowCoord.xy), receiver, uvPerTangent);
543
+ // The receiver's plane at a tap offset, as a distance and as a [0, 1] depth.
544
+ const planeDistance = (offset: Node<"vec2">) =>
545
+ max(near, receiver.add(slope.x.mul(offset.x)).add(slope.y.mul(offset.y)));
546
+ const planeDepth = (offset: Node<"vec2">) => depthOf(planeDistance(offset));
547
+ const visibility = float(1).toVar();
548
+ const cone = searchOf(receiver).toVar();
549
+ const pass = (index: number) => {
550
+ const last = index + 1 === blockerPasses;
551
+ const sum = float(0).toVar();
552
+ const count = float(0).toVar();
553
+ const nearest = float(1e30).toVar();
554
+ const visit = (offset: Node<"vec2">, own: boolean) => {
555
+ const depth = load(shadowCoord.xy.add(offset.mul(uvPerTangent))).toVar();
556
+ If(depth.lessThan(planeDepth(offset)), () => {
557
+ const blocker = distanceOf(depth);
558
+ if (!last) {
559
+ nearest.assign(min(nearest, blocker));
560
+ count.addAssign(1);
561
+ return;
562
+ }
563
+ const shade = () => {
564
+ sum.addAssign(blocker);
565
+ count.addAssign(1);
566
+ };
567
+ // The receiver's own ray is inside the lamp's disk; any other texel shades the receiver only
568
+ // when its own penumbra reaches it.
569
+ if (own) shade();
570
+ else If(offset.length().lessThanEqual(spreadOf(blocker, planeDistance(offset))), shade);
571
+ });
572
+ };
573
+ visit(vec2(0, 0), true);
574
+ for (let tapIndex = 0; tapIndex < blockerSamples; tapIndex++)
575
+ visit(disk(tapIndex, blockerSamples).mul(cone), false);
576
+ If(count.greaterThan(0), () => {
577
+ if (!last) {
578
+ cone.assign(min(cone, spreadOf(nearest, receiver)));
579
+ pass(index + 1);
580
+ return;
581
+ }
582
+ const blocker = sum.div(count);
583
+ const penumbra = penumbraOf(blocker, receiver, tanHalf.mul(2).div(size)).toVar();
584
+ const lit = float(0).toVar();
585
+ for (let tapIndex = 0; tapIndex < filterSamples; tapIndex++) {
586
+ const offset = disk(tapIndex, filterSamples).mul(penumbra);
587
+ lit.addAssign(
588
+ step(planeDepth(offset), load(shadowCoord.xy.add(offset.mul(uvPerTangent)))),
589
+ );
590
+ }
591
+ visibility.assign(lit.div(filterSamples));
592
+ });
593
+ };
594
+ pass(0);
595
+ return visibility;
596
+ })();
597
+ };
598
+ // The owned engine reads the same parameters from this tag (a lamp's filterNode).
599
+ return Object.assign(filter, {
600
+ [Symbol.for("threenative.sourceRadiusShadowFilter")]: Object.freeze({
601
+ sourceRadius,
602
+ blockerSamples,
603
+ filterSamples,
604
+ penumbraScale,
605
+ }),
606
+ });
607
+ }