@threenative/core 0.3.4 → 0.3.6

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 (176) hide show
  1. package/capabilities.json +1505 -79
  2. package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
  3. package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
  4. package/dist/{game-CljaDv4D.d.ts → game-Jz4Fdoeb.d.ts} +114 -11
  5. package/dist/hot.d.ts +4 -4
  6. package/dist/index.d.ts +712 -118
  7. package/dist/index.js +12437 -4955
  8. package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
  9. package/dist/playtest.d.ts +6 -10
  10. package/dist/playtest.js +57 -24
  11. package/dist/react-css.d.ts +62 -0
  12. package/dist/react-css.js +591 -0
  13. package/dist/react.d.ts +2 -2
  14. package/dist/{renderer-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
  15. package/dist/terrain-jobs-worker.d.ts +2 -0
  16. package/dist/terrain-jobs-worker.js +130 -0
  17. package/dist/ui-layer.js +59 -8
  18. package/dist/world.d.ts +766 -73
  19. package/dist/world.js +9307 -3543
  20. package/gpl/recipes/export_world.py +18 -1
  21. package/mcp/blender-server.mjs +7 -4
  22. package/mcp/blender.mjs +3 -4
  23. package/mcp/engine-server.mjs +2 -2
  24. package/mcp/servers.mjs +4 -4
  25. package/package.json +15 -9
  26. package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
  27. package/patches/three@0.185.1.patch +6594 -700
  28. package/scripts/apply-three-patch.mjs +62 -4
  29. package/src/animation-blend.ts +264 -0
  30. package/src/animation-composition.ts +362 -0
  31. package/src/animation-layers.ts +260 -0
  32. package/src/animation-root-motion.ts +283 -0
  33. package/src/animation.ts +896 -0
  34. package/src/assets.ts +1303 -0
  35. package/src/atmosphere/index.ts +335 -0
  36. package/src/atmosphere/luts.ts +298 -0
  37. package/src/atmosphere/params.ts +323 -0
  38. package/src/audio.ts +912 -0
  39. package/src/billboard.ts +124 -0
  40. package/src/bone-lengths.ts +157 -0
  41. package/src/camera-shake.ts +116 -0
  42. package/src/canvas-layer.ts +47 -0
  43. package/src/clip-audit.ts +401 -0
  44. package/src/clustered-batch.ts +492 -0
  45. package/src/clustered-mesh.ts +638 -0
  46. package/src/compute-driven.ts +176 -0
  47. package/src/compute-timing.ts +318 -0
  48. package/src/config.ts +593 -0
  49. package/src/debug.ts +82 -0
  50. package/src/engine-render-hook.ts +25 -0
  51. package/src/entities.ts +79 -0
  52. package/src/entity-snapshot.ts +53 -0
  53. package/src/flight.ts +683 -0
  54. package/src/fluid-field.ts +748 -0
  55. package/src/fluid-particles.ts +1253 -0
  56. package/src/frame-budget.ts +1368 -0
  57. package/src/game.ts +2408 -0
  58. package/src/geometry-capture.ts +1098 -0
  59. package/src/gpu-class.ts +160 -0
  60. package/src/gpu-frame-observation.ts +424 -0
  61. package/src/gpu-readback.ts +143 -0
  62. package/src/gpu-scene-bvh.ts +464 -0
  63. package/src/grounding.ts +100 -0
  64. package/src/hot.ts +161 -0
  65. package/src/import-meta.d.ts +13 -0
  66. package/src/index.ts +1536 -0
  67. package/src/input.ts +690 -0
  68. package/src/instanced-batch-lod.ts +283 -0
  69. package/src/instanced-batch.ts +274 -0
  70. package/src/interpolation.ts +129 -0
  71. package/src/launch-diagnostics.ts +161 -0
  72. package/src/loop.ts +574 -0
  73. package/src/matrix-world.ts +245 -0
  74. package/src/merge-parts.ts +812 -0
  75. package/src/model-lod.ts +1315 -0
  76. package/src/net-protocol.ts +333 -0
  77. package/src/net-session.ts +477 -0
  78. package/src/net.ts +80 -0
  79. package/src/ocean/fft.ts +72 -0
  80. package/src/ocean/spectral.ts +728 -0
  81. package/src/particle-significance.ts +102 -0
  82. package/src/particles.ts +648 -0
  83. package/src/path-follow.ts +175 -0
  84. package/src/picking.ts +250 -0
  85. package/src/pipeline-census.ts +1566 -0
  86. package/src/platform.ts +210 -0
  87. package/src/playtest.ts +850 -0
  88. package/src/pointer-events.ts +411 -0
  89. package/src/pose-measure.ts +435 -0
  90. package/src/profiling/FrameCounters.ts +231 -0
  91. package/src/profiling/Spans.ts +548 -0
  92. package/src/profiling/opacity-convention.ts +21 -0
  93. package/src/profiling/render-list-validate.ts +175 -0
  94. package/src/profiling/render-trap-audit.ts +84 -0
  95. package/src/profiling/scene-warning.ts +190 -0
  96. package/src/profiling/span-probes.ts +191 -0
  97. package/src/profiling/unlit-foliage-warning.ts +149 -0
  98. package/src/projection-apply.ts +1529 -0
  99. package/src/projection-marker.ts +142 -0
  100. package/src/projection-plan.ts +1258 -0
  101. package/src/projection-skinned.ts +419 -0
  102. package/src/projection-stability.ts +409 -0
  103. package/src/projection-uniform.ts +328 -0
  104. package/src/random.ts +41 -0
  105. package/src/react-css.ts +604 -0
  106. package/src/react-glyphs.ts +114 -0
  107. package/src/react-host.ts +576 -0
  108. package/src/react-layout.ts +265 -0
  109. package/src/react.ts +60 -0
  110. package/src/render/alpha-antialiasing.ts +159 -0
  111. package/src/render/batched-velocity.ts +126 -0
  112. package/src/render/chain.ts +1021 -0
  113. package/src/render/daylight.ts +189 -0
  114. package/src/render/depth-pyramid.ts +596 -0
  115. package/src/render/foliage-alpha.ts +166 -0
  116. package/src/render/material-key.ts +60 -0
  117. package/src/render/mesh-pool.ts +144 -0
  118. package/src/render/probe-volume.ts +1668 -0
  119. package/src/render/resolution-subrect.ts +253 -0
  120. package/src/render/velocity.ts +442 -0
  121. package/src/render/virtual-shadow-pages.ts +827 -0
  122. package/src/render/virtual-shadow-partial.ts +174 -0
  123. package/src/render/virtual-shadow.ts +3330 -0
  124. package/src/render/world-impostor-surface.ts +722 -0
  125. package/src/render/world-impostor.ts +558 -0
  126. package/src/render-camera-cull.ts +441 -0
  127. package/src/render-pass-budget.ts +501 -0
  128. package/src/renderProjection.ts +758 -0
  129. package/src/renderer-config.ts +127 -0
  130. package/src/renderer.ts +1847 -0
  131. package/src/replay-protocol.ts +85 -0
  132. package/src/replay.ts +205 -0
  133. package/src/resolution-scaler.ts +819 -0
  134. package/src/rig-preparation.ts +271 -0
  135. package/src/ripple-field.ts +432 -0
  136. package/src/scale.ts +109 -0
  137. package/src/scene.ts +239 -0
  138. package/src/schedule.ts +155 -0
  139. package/src/skeletal-mesh.ts +61 -0
  140. package/src/skeleton.ts +100 -0
  141. package/src/snow-field.ts +744 -0
  142. package/src/softbody-topology.ts +269 -0
  143. package/src/softbody.ts +516 -0
  144. package/src/sprite-animator.ts +222 -0
  145. package/src/startup-readiness.ts +386 -0
  146. package/src/state.ts +66 -0
  147. package/src/static-transform.ts +274 -0
  148. package/src/storage-buffer.ts +253 -0
  149. package/src/streaming.ts +308 -0
  150. package/src/target-fps.ts +92 -0
  151. package/src/terrain-jobs-worker.ts +17 -0
  152. package/src/terrain-jobs.ts +353 -0
  153. package/src/textures.ts +39 -0
  154. package/src/tracers.ts +237 -0
  155. package/src/ui-bridge.ts +368 -0
  156. package/src/ui-hit-regions.ts +380 -0
  157. package/src/ui-layer.ts +83 -0
  158. package/src/ui-state.ts +220 -0
  159. package/src/version.ts +2 -0
  160. package/src/viewport.ts +253 -0
  161. package/src/warmup.ts +1357 -0
  162. package/src/water-surface.ts +384 -0
  163. package/src/wave-field.ts +524 -0
  164. package/src/world-capabilities.ts +131 -0
  165. package/src/world-cell-proxy.ts +392 -0
  166. package/src/world-cells.ts +10564 -0
  167. package/src/world-gpu-scene.ts +3354 -0
  168. package/src/world-heightmap.ts +82 -0
  169. package/src/world-package.ts +469 -0
  170. package/src/world-passes.ts +582 -0
  171. package/src/world-region.ts +17 -0
  172. package/src/world-terrain-splat.ts +564 -0
  173. package/src/world-tiles.ts +3826 -0
  174. package/src/world-topology.ts +370 -0
  175. package/src/world-validate.ts +48 -0
  176. package/src/world.ts +805 -0
@@ -0,0 +1,384 @@
1
+ import { Box3, type Camera, type Mesh, type Object3D, Quaternion, Vector3 } from "three";
2
+ import {
3
+ cameraFar,
4
+ cameraNear,
5
+ clamp,
6
+ float,
7
+ linearDepth,
8
+ reflector,
9
+ screenUV,
10
+ select,
11
+ vec2,
12
+ viewportDepthTexture,
13
+ viewportLinearDepth,
14
+ viewportSharedTexture,
15
+ } from "three/tsl";
16
+ import type { Node } from "three/webgpu";
17
+
18
+ /** What the mirrored pass costs: how big it is, how many of them, and how much of the world. */
19
+ export interface IWaterReflectionOptions {
20
+ /**
21
+ * The mirrored pass's render target, as a fraction of the drawing buffer.
22
+ *
23
+ * How many *pixels* the second pass costs. Half is the usual answer. This is not on its own the
24
+ * number that decides whether a surface is affordable, and a game that reads it that way will
25
+ * measure no improvement and conclude its water is free: a scene with many objects is bound by
26
+ * the draw calls the mirrored pass submits, not by its pixels, and those do not shrink with the
27
+ * target. Measured on `sandbox/midway-open-pacific` at 1920x1080 on an nvidia/turing adapter with
28
+ * 1,965 draws in the frame, halving this again — 0.5 to 0.25 — moved GPU p95 from 17.80 ms to
29
+ * 17.58 ms. Removing the pass entirely moved it to 7.67 ms. `layers` is the number that mattered.
30
+ */
31
+ readonly resolutionScale: number;
32
+ /** Whether this surface may appear in other reflectors' passes. Off is one pass; on is n². */
33
+ readonly bounces?: boolean;
34
+ /**
35
+ * Explicit Three Layers mask. Wins over automatic selection, including `1` (all layer-0 props).
36
+ * Omit to reflect terrain-sized surfaces and large non-instanced shadow casters. Instanced and
37
+ * skinned props are excluded automatically; sky/background and lighting remain available.
38
+ */
39
+ readonly layers?: number;
40
+ /** Minimum world-space extent for automatic terrain/casters, in metres. Default 10. */
41
+ readonly minSize?: number;
42
+ /**
43
+ * How often the mirrored pass redraws, in presented frames.
44
+ *
45
+ * The reflection is a second render of the world and on a crowded sea it is the largest single
46
+ * item in the frame. It is also low-frequency: a swell, a hull and a wake read the same whether
47
+ * the mirror was taken this frame or two frames ago, and at speed the eye cannot hold a reflected
48
+ * silhouette still enough to notice it lag. `2` redraws every second frame and samples the
49
+ * previous frame's target in between, halving the pass's cost; a higher number halves it again.
50
+ *
51
+ * Omit it — or pass `1` — and the pass redraws every frame, which is the shipping behaviour and
52
+ * the default. The trade is temporal: while the camera moves, the reflection is up to
53
+ * `refreshInterval - 1` frames behind the scene it mirrors. Fast camera motion can make a
54
+ * reflected edge shimmer, and a moving object's reflection trails it. A still camera sees none of
55
+ * that, so name it only where the measured pass dominates the frame.
56
+ */
57
+ readonly refreshInterval?: number;
58
+ }
59
+
60
+ export interface IWaterSurfaceOptions {
61
+ /** World-space height of the surface, in metres. The mirror plane, and where thickness is 0. */
62
+ readonly level: number;
63
+ /**
64
+ * Thickness readings saturate here, in metres.
65
+ *
66
+ * A required number because it is the range of the instrument, not a taste: sky behind the
67
+ * surface has no depth at all, and something has to be reported for it.
68
+ */
69
+ readonly maxThickness: number;
70
+ /** Omit for a surface that reflects nothing; `reflectionAt` then throws rather than lying. */
71
+ readonly reflection?: IWaterReflectionOptions;
72
+ }
73
+
74
+ /**
75
+ * The pass three hangs off the node `reflector()` returns. Its virtual cameras are the only place a
76
+ * layer mask can be applied, and `updateBefore` is the whole second render, so those are the two
77
+ * seams this file needs named rather than cast at each use.
78
+ */
79
+ interface IReflectorPass {
80
+ getVirtualCamera(camera: Camera): Camera;
81
+ updateBefore(frame: IReflectionFrame): void;
82
+ /** three's NodeUpdateType; `"none"` when the back end draws the pass itself (the native engine). */
83
+ readonly updateBeforeType?: string;
84
+ }
85
+ interface IReflectionFrame {
86
+ readonly scene: Object3D;
87
+ readonly renderer: unknown;
88
+ }
89
+ interface IReflectorWithPass {
90
+ _reflectorBaseNode: IReflectorPass;
91
+ }
92
+
93
+ const UP = new Vector3(0, 1, 0);
94
+ const FORWARD = new Vector3(0, 0, 1);
95
+ /** The one rotation that turns the reflector target's local +Z into world up. */
96
+ const FACING_UP = new Quaternion().setFromUnitVectors(FORWARD, UP);
97
+
98
+ function finite(name: string, value: number): number {
99
+ if (typeof value !== "number" || !Number.isFinite(value))
100
+ throw new Error(`WaterSurface3D.${name} must be finite.`);
101
+ return value;
102
+ }
103
+
104
+ /**
105
+ * What a horizontal water surface can see: the world mirrored in it, the world beneath it, and
106
+ * how much water stands between the two.
107
+ *
108
+ * This is the render plumbing a water material needs and cannot write portably — a mirrored
109
+ * camera and its render target, the frame's own colour read back as the light coming up through
110
+ * the surface, and the scene's depth turned into **metres of water under this pixel**. It decides
111
+ * nothing about how any of that looks: no colour, no absorption tint, no fresnel weighting, no
112
+ * glint. Those are the game's, composed from the nodes below in its own `src/render/` material.
113
+ *
114
+ * The depth reading is the part worth having. `linearDepth` answers in a normalised 0..1 that
115
+ * changes meaning with every camera near/far pair, so a material that subtracts two of them gets
116
+ * a number in no unit at all, and its shoreline moves when the camera's far plane does.
117
+ * `thicknessAt` returns metres, and metres survive the camera changing.
118
+ *
119
+ * ```js
120
+ * const surface = new WaterSurface3D({ level: 0, maxThickness: 4, reflection: { resolutionScale: 0.5 } });
121
+ * const offset = normal.xz.mul(0.02);
122
+ * material.colorNode = mix(
123
+ * surface.refractionAt(offset).mul(siltTint), // the game's colours,
124
+ * surface.reflectionAt(offset), // composed by the game,
125
+ * fresnel, // with the game's own fresnel.
126
+ * );
127
+ * material.opacityNode = surface.thicknessAt().div(surface.maxThickness);
128
+ * ```
129
+ */
130
+ export class WaterSurface3D {
131
+ readonly maxThickness: number;
132
+ /**
133
+ * The object whose plane is mirrored, kept outside the scene graph on purpose.
134
+ *
135
+ * A water level is a fact about the world, not about the mesh that happens to draw it: parent
136
+ * the mirror to the surface mesh, as three's own examples do, and a non-uniform scale anywhere
137
+ * up that mesh's ancestry skews the plane the reflection is taken about. This one is placed
138
+ * from `level` and nothing else, so it stays level.
139
+ */
140
+ readonly target: Object3D | undefined;
141
+ #level: number;
142
+ #reflector: ReturnType<typeof reflector> | undefined;
143
+ #released = false;
144
+
145
+ constructor(options: IWaterSurfaceOptions) {
146
+ if (options === undefined || typeof options !== "object")
147
+ throw new Error("WaterSurface3D requires options.");
148
+ this.#level = finite("level", options.level);
149
+ this.maxThickness = finite("maxThickness", options.maxThickness);
150
+ if (this.maxThickness <= 0) throw new Error("WaterSurface3D.maxThickness must be positive.");
151
+ const reflection = options.reflection;
152
+ if (reflection === undefined) {
153
+ this.reflectionRefreshInterval = 1;
154
+ this.target = undefined;
155
+ return;
156
+ }
157
+ if (reflection === null || typeof reflection !== "object")
158
+ throw new Error("WaterSurface3D.reflection must be an object.");
159
+ const resolutionScale = finite("reflection.resolutionScale", reflection.resolutionScale);
160
+ if (resolutionScale <= 0 || resolutionScale > 1)
161
+ throw new Error("WaterSurface3D.reflection.resolutionScale must be within (0, 1].");
162
+ const refreshInterval = reflection.refreshInterval ?? 1;
163
+ if (!Number.isInteger(refreshInterval) || refreshInterval < 1)
164
+ throw new Error("WaterSurface3D.reflection.refreshInterval must be a positive integer.");
165
+ const node = reflector({
166
+ bounces: reflection.bounces === true,
167
+ generateMipmaps: false,
168
+ resolutionScale,
169
+ });
170
+ this.reflectionLayers = reflection.layers;
171
+ this.reflectionRefreshInterval = refreshInterval;
172
+ // `reflector()` returns the texture node; the pass itself — and the virtual cameras and render
173
+ // it owns — live on the reflector base node hanging off it.
174
+ const pass = (node as unknown as IReflectorWithPass)._reflectorBaseNode; // quality-allow: three 0.185 does not type `_reflectorBaseNode` on the reflector node it returns
175
+ // Three runs this from the draw of the first object that samples the reflection, and without
176
+ // `bounces` the node updates per frame, so an opaque water mesh in a world chunk is bundle-safe
177
+ // and that draw can be part of a `BundleGroup` the main pass is recording. Three keeps that
178
+ // bundle in `_currentRenderBundle` and does not save it across the nested `render()` the mirror
179
+ // is: the mirror's draws would be filed under the main bundle, and the mirror's own bundles
180
+ // leave the field `null`, so the main bundle's remaining draws are recorded but never listed —
181
+ // a replay refreshes only listed draws, so those keep the camera they were recorded with. The
182
+ // mirror renders outside the record, and the record gets its bundle back. A pass three never
183
+ // updates (the native engine draws it and records no JS bundle) has no render to guard.
184
+ if (pass.updateBeforeType !== "none") {
185
+ const mirror = pass.updateBefore.bind(pass);
186
+ pass.updateBefore = (frame: IReflectionFrame): void => {
187
+ const host = frame.renderer as { _currentRenderBundle?: unknown };
188
+ const recording = host._currentRenderBundle;
189
+ if (recording !== undefined) host._currentRenderBundle = null;
190
+ try {
191
+ mirror(frame);
192
+ } finally {
193
+ if (recording !== undefined) host._currentRenderBundle = recording;
194
+ }
195
+ };
196
+ }
197
+ if (reflection.layers !== undefined) {
198
+ const mask = reflection.layers;
199
+ if (!Number.isInteger(mask) || mask < 0)
200
+ throw new Error("WaterSurface3D.reflection.layers must be a non-negative integer mask.");
201
+ // The pass mints one virtual camera per scene camera, lazily, inside three. There is no
202
+ // constructor seam for it and no list to walk afterwards, so the mask is applied where every
203
+ // such camera is born. A camera three has already handed out is caught too, because the same
204
+ // call returns it.
205
+ const mint = pass.getVirtualCamera.bind(pass);
206
+ pass.getVirtualCamera = (camera: Camera): Camera => {
207
+ const virtual = mint(camera);
208
+ virtual.layers.mask = mask;
209
+ return virtual;
210
+ };
211
+ }
212
+ if (reflection.layers === undefined) {
213
+ const minSize = finite("reflection.minSize", reflection.minSize ?? 10);
214
+ if (minSize <= 0) throw new Error("WaterSurface3D.reflection.minSize must be positive.");
215
+ const render = pass.updateBefore.bind(pass);
216
+ const bounds = new Box3();
217
+ const size = new Vector3();
218
+ let reported = false;
219
+ pass.updateBefore = (frame: IReflectionFrame): void => {
220
+ const hidden: { object: Object3D; mask: number }[] = [];
221
+ let included = 0;
222
+ // Layer filtering is pass-local: the main scene and every explicit-layer mirror keep their set.
223
+ // Reject only the mesh, retaining children such as the terrain's distant horizon.
224
+ frame.scene.traverse((object) => {
225
+ const mesh = object as Mesh & { isInstancedMesh?: boolean; isSkinnedMesh?: boolean };
226
+ if (mesh.isMesh !== true || !mesh.visible) return;
227
+ let keep = false;
228
+ if (mesh.isInstancedMesh !== true && mesh.isSkinnedMesh !== true) {
229
+ if (mesh.geometry.boundingBox === null) mesh.geometry.computeBoundingBox();
230
+ if (mesh.geometry.boundingBox !== null) {
231
+ bounds.copy(mesh.geometry.boundingBox).applyMatrix4(mesh.matrixWorld).getSize(size);
232
+ const horizontal = Math.max(size.x, size.z);
233
+ const terrain = horizontal >= minSize && size.y <= Math.min(size.x, size.z) * 0.5;
234
+ keep = terrain || (mesh.castShadow && Math.max(size.x, size.y, size.z) >= minSize);
235
+ }
236
+ }
237
+ if (keep) included += 1;
238
+ else {
239
+ hidden.push({ object: mesh, mask: mesh.layers.mask });
240
+ mesh.layers.mask = 0;
241
+ }
242
+ });
243
+ if (!reported) {
244
+ console.info(
245
+ `TN_WATER_REFLECTION_DEFAULT: ${JSON.stringify({ included, excluded: hidden.length, minSize })}`,
246
+ );
247
+ reported = true;
248
+ }
249
+ try {
250
+ render(frame);
251
+ } finally {
252
+ for (const { object, mask } of hidden) object.layers.mask = mask;
253
+ }
254
+ };
255
+ }
256
+ if (refreshInterval > 1) {
257
+ // Every frame the pass redraws the world into its target and binds the result. The render is
258
+ // the expensive part; the binding is not. Skipping the whole `updateBefore` on the frames
259
+ // between leaves the previous frame's texture bound and the render target intact, so the
260
+ // material samples the last mirror rather than an empty one. `refreshInterval` counts calls,
261
+ // which is the presented-frame count for a surface built without `bounces` — that is the
262
+ // default, and the node only updates once per frame for it.
263
+ const render = pass.updateBefore.bind(pass);
264
+ let calls = 0;
265
+ pass.updateBefore = (frame: IReflectionFrame): void => {
266
+ if (calls % refreshInterval === 0) render(frame);
267
+ calls += 1;
268
+ };
269
+ }
270
+ this.#reflector = node;
271
+ this.target = node.target;
272
+ node.target.matrixAutoUpdate = false;
273
+ node.target.matrixWorldAutoUpdate = false;
274
+ this.#placeTarget();
275
+ }
276
+
277
+ /**
278
+ * The camera the mirrored pass draws this surface with, for one scene camera.
279
+ *
280
+ * The pass mints one of these per scene camera, lazily, and reflects the camera through the
281
+ * mirror plane each frame. It is exposed because `layers` is not the only thing a game may need
282
+ * to say about the second draw — a near/far pair is the other — and because a reflection you
283
+ * cannot inspect is a reflection you cannot cost. Undefined when this surface has no reflection.
284
+ */
285
+ reflectionCameraFor(camera: Camera): Camera | undefined {
286
+ if (this.#reflector === undefined) return undefined;
287
+ // quality-allow: three 0.185 does not type `_reflectorBaseNode` on the reflector node it returns
288
+ return (this.#reflector as unknown as IReflectorWithPass)._reflectorBaseNode.getVirtualCamera(
289
+ camera,
290
+ );
291
+ }
292
+
293
+ /** Explicit mask supplied by the game. Undefined means automatic terrain/large-caster selection. */
294
+ readonly reflectionLayers: number | undefined;
295
+
296
+ /** How often the mirrored pass redraws, in presented frames. `1` is every frame, the default. */
297
+ readonly reflectionRefreshInterval: number;
298
+
299
+ /** The world-space height of the surface, in metres. */
300
+ get level(): number {
301
+ return this.#level;
302
+ }
303
+
304
+ /** Move the surface — a tide, a sluice, a flooding room. The mirror plane follows. */
305
+ setLevel(value: number): void {
306
+ if (this.#released) throw new Error("WaterSurface3D is released.");
307
+ this.#level = finite("level", value);
308
+ this.#placeTarget();
309
+ }
310
+
311
+ get released(): boolean {
312
+ return this.#released;
313
+ }
314
+
315
+ #placeTarget(): void {
316
+ const target = this.target;
317
+ if (target === undefined) return;
318
+ target.position.set(0, this.#level, 0);
319
+ target.quaternion.copy(FACING_UP);
320
+ target.scale.set(1, 1, 1);
321
+ target.updateMatrix();
322
+ // Nothing else will: the target is deliberately not in the scene graph.
323
+ target.matrixWorld.copy(target.matrix);
324
+ }
325
+
326
+ /**
327
+ * The world mirrored in the surface, at an optional screen-space offset.
328
+ *
329
+ * The offset is where a game spends its surface normal: a still mirror takes none, and ripples
330
+ * are the normal's horizontal part scaled by however far the game wants the reflection to slide.
331
+ */
332
+ reflectionAt(offset?: Node<"vec2">): Node<"vec3"> {
333
+ const node = this.#reflector;
334
+ if (node === undefined)
335
+ throw new Error("WaterSurface3D was built without reflection; there is nothing to sample.");
336
+ if (offset === undefined) return node.rgb as unknown as Node<"vec3">; // quality-allow: TSL result shape is set by construction; three 0.185 types swizzles and Fn loosely
337
+ // The mirrored pass is flipped in x; the offset rides on top of that, not instead of it.
338
+ return node.sample(clamp(screenUV.flipX().add(offset), vec2(0, 0), vec2(1, 1)))
339
+ .rgb as unknown as Node<"vec3">; // quality-allow: TSL result shape is set by construction; three 0.185 types swizzles and Fn loosely
340
+ }
341
+
342
+ /**
343
+ * The frame beneath the surface — everything already drawn this frame, read at an offset.
344
+ *
345
+ * An offset that lands on something **in front of** the water is refused and the fragment falls
346
+ * back to a straight read. Without that, a rock standing in the shallows smears across the
347
+ * water in front of it: the classic refraction bleed, and the reason a hand-rolled offset looks
348
+ * wrong the first time every game writes one.
349
+ */
350
+ refractionAt(offset?: Node<"vec2">): Node<"vec3"> {
351
+ if (offset === undefined) return viewportSharedTexture().rgb as unknown as Node<"vec3">; // quality-allow: TSL result shape is set by construction; three 0.185 types swizzles and Fn loosely
352
+ const safe = select(this.thicknessAt(offset).greaterThan(float(0)), offset, vec2(0, 0));
353
+ return viewportSharedTexture(clamp(screenUV.add(safe), vec2(0, 0), vec2(1, 1)))
354
+ .rgb as unknown as Node<"vec3">; // quality-allow: TSL result shape is set by construction; three 0.185 types swizzles and Fn loosely
355
+ }
356
+
357
+ /**
358
+ * Metres of water between this fragment and whatever is drawn behind it, clamped to
359
+ * `maxThickness`. Zero exactly where the bed meets the surface, which is the shoreline.
360
+ *
361
+ * Sky behind the surface has no depth and reads as `maxThickness`, not as zero: an unbounded
362
+ * horizon is deep water, not dry land.
363
+ */
364
+ thicknessAt(offset?: Node<"vec2">): Node<"float"> {
365
+ const behind =
366
+ offset === undefined
367
+ ? viewportLinearDepth
368
+ : linearDepth(viewportDepthTexture(clamp(screenUV.add(offset), vec2(0, 0), vec2(1, 1))));
369
+ // `linearDepth` answers in a 0..1 normalised by the camera's near and far. Undo that here,
370
+ // once, so every reading downstream is in metres and stays in metres when the camera changes.
371
+ const span = cameraFar.sub(cameraNear);
372
+ const metres = behind.sub(linearDepth()).mul(span);
373
+ return clamp(metres, float(0), float(this.maxThickness)) as unknown as Node<"float">; // quality-allow: TSL result shape is set by construction; three 0.185 types swizzles and Fn loosely
374
+ }
375
+
376
+ /** Drop the mirrored pass and its render target. */
377
+ dispose(): void {
378
+ if (this.#released) return;
379
+ this.#released = true;
380
+ this.target?.removeFromParent();
381
+ this.#reflector?.dispose();
382
+ this.#reflector = undefined;
383
+ }
384
+ }