@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.
- package/capabilities.json +1505 -79
- package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
- package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
- package/dist/{game-CljaDv4D.d.ts → game-Jz4Fdoeb.d.ts} +114 -11
- package/dist/hot.d.ts +4 -4
- package/dist/index.d.ts +712 -118
- package/dist/index.js +12437 -4955
- package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
- package/dist/playtest.d.ts +6 -10
- package/dist/playtest.js +57 -24
- package/dist/react-css.d.ts +62 -0
- package/dist/react-css.js +591 -0
- package/dist/react.d.ts +2 -2
- package/dist/{renderer-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
- package/dist/terrain-jobs-worker.d.ts +2 -0
- package/dist/terrain-jobs-worker.js +130 -0
- package/dist/ui-layer.js +59 -8
- package/dist/world.d.ts +766 -73
- package/dist/world.js +9307 -3543
- package/gpl/recipes/export_world.py +18 -1
- package/mcp/blender-server.mjs +7 -4
- package/mcp/blender.mjs +3 -4
- package/mcp/engine-server.mjs +2 -2
- package/mcp/servers.mjs +4 -4
- package/package.json +15 -9
- package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
- package/patches/three@0.185.1.patch +6594 -700
- package/scripts/apply-three-patch.mjs +62 -4
- package/src/animation-blend.ts +264 -0
- package/src/animation-composition.ts +362 -0
- package/src/animation-layers.ts +260 -0
- package/src/animation-root-motion.ts +283 -0
- package/src/animation.ts +896 -0
- package/src/assets.ts +1303 -0
- package/src/atmosphere/index.ts +335 -0
- package/src/atmosphere/luts.ts +298 -0
- package/src/atmosphere/params.ts +323 -0
- package/src/audio.ts +912 -0
- package/src/billboard.ts +124 -0
- package/src/bone-lengths.ts +157 -0
- package/src/camera-shake.ts +116 -0
- package/src/canvas-layer.ts +47 -0
- package/src/clip-audit.ts +401 -0
- package/src/clustered-batch.ts +492 -0
- package/src/clustered-mesh.ts +638 -0
- package/src/compute-driven.ts +176 -0
- package/src/compute-timing.ts +318 -0
- package/src/config.ts +593 -0
- package/src/debug.ts +82 -0
- package/src/engine-render-hook.ts +25 -0
- package/src/entities.ts +79 -0
- package/src/entity-snapshot.ts +53 -0
- package/src/flight.ts +683 -0
- package/src/fluid-field.ts +748 -0
- package/src/fluid-particles.ts +1253 -0
- package/src/frame-budget.ts +1368 -0
- package/src/game.ts +2408 -0
- package/src/geometry-capture.ts +1098 -0
- package/src/gpu-class.ts +160 -0
- package/src/gpu-frame-observation.ts +424 -0
- package/src/gpu-readback.ts +143 -0
- package/src/gpu-scene-bvh.ts +464 -0
- package/src/grounding.ts +100 -0
- package/src/hot.ts +161 -0
- package/src/import-meta.d.ts +13 -0
- package/src/index.ts +1536 -0
- package/src/input.ts +690 -0
- package/src/instanced-batch-lod.ts +283 -0
- package/src/instanced-batch.ts +274 -0
- package/src/interpolation.ts +129 -0
- package/src/launch-diagnostics.ts +161 -0
- package/src/loop.ts +574 -0
- package/src/matrix-world.ts +245 -0
- package/src/merge-parts.ts +812 -0
- package/src/model-lod.ts +1315 -0
- package/src/net-protocol.ts +333 -0
- package/src/net-session.ts +477 -0
- package/src/net.ts +80 -0
- package/src/ocean/fft.ts +72 -0
- package/src/ocean/spectral.ts +728 -0
- package/src/particle-significance.ts +102 -0
- package/src/particles.ts +648 -0
- package/src/path-follow.ts +175 -0
- package/src/picking.ts +250 -0
- package/src/pipeline-census.ts +1566 -0
- package/src/platform.ts +210 -0
- package/src/playtest.ts +850 -0
- package/src/pointer-events.ts +411 -0
- package/src/pose-measure.ts +435 -0
- package/src/profiling/FrameCounters.ts +231 -0
- package/src/profiling/Spans.ts +548 -0
- package/src/profiling/opacity-convention.ts +21 -0
- package/src/profiling/render-list-validate.ts +175 -0
- package/src/profiling/render-trap-audit.ts +84 -0
- package/src/profiling/scene-warning.ts +190 -0
- package/src/profiling/span-probes.ts +191 -0
- package/src/profiling/unlit-foliage-warning.ts +149 -0
- package/src/projection-apply.ts +1529 -0
- package/src/projection-marker.ts +142 -0
- package/src/projection-plan.ts +1258 -0
- package/src/projection-skinned.ts +419 -0
- package/src/projection-stability.ts +409 -0
- package/src/projection-uniform.ts +328 -0
- package/src/random.ts +41 -0
- package/src/react-css.ts +604 -0
- package/src/react-glyphs.ts +114 -0
- package/src/react-host.ts +576 -0
- package/src/react-layout.ts +265 -0
- package/src/react.ts +60 -0
- package/src/render/alpha-antialiasing.ts +159 -0
- package/src/render/batched-velocity.ts +126 -0
- package/src/render/chain.ts +1021 -0
- package/src/render/daylight.ts +189 -0
- package/src/render/depth-pyramid.ts +596 -0
- package/src/render/foliage-alpha.ts +166 -0
- package/src/render/material-key.ts +60 -0
- package/src/render/mesh-pool.ts +144 -0
- package/src/render/probe-volume.ts +1668 -0
- package/src/render/resolution-subrect.ts +253 -0
- package/src/render/velocity.ts +442 -0
- package/src/render/virtual-shadow-pages.ts +827 -0
- package/src/render/virtual-shadow-partial.ts +174 -0
- package/src/render/virtual-shadow.ts +3330 -0
- package/src/render/world-impostor-surface.ts +722 -0
- package/src/render/world-impostor.ts +558 -0
- package/src/render-camera-cull.ts +441 -0
- package/src/render-pass-budget.ts +501 -0
- package/src/renderProjection.ts +758 -0
- package/src/renderer-config.ts +127 -0
- package/src/renderer.ts +1847 -0
- package/src/replay-protocol.ts +85 -0
- package/src/replay.ts +205 -0
- package/src/resolution-scaler.ts +819 -0
- package/src/rig-preparation.ts +271 -0
- package/src/ripple-field.ts +432 -0
- package/src/scale.ts +109 -0
- package/src/scene.ts +239 -0
- package/src/schedule.ts +155 -0
- package/src/skeletal-mesh.ts +61 -0
- package/src/skeleton.ts +100 -0
- package/src/snow-field.ts +744 -0
- package/src/softbody-topology.ts +269 -0
- package/src/softbody.ts +516 -0
- package/src/sprite-animator.ts +222 -0
- package/src/startup-readiness.ts +386 -0
- package/src/state.ts +66 -0
- package/src/static-transform.ts +274 -0
- package/src/storage-buffer.ts +253 -0
- package/src/streaming.ts +308 -0
- package/src/target-fps.ts +92 -0
- package/src/terrain-jobs-worker.ts +17 -0
- package/src/terrain-jobs.ts +353 -0
- package/src/textures.ts +39 -0
- package/src/tracers.ts +237 -0
- package/src/ui-bridge.ts +368 -0
- package/src/ui-hit-regions.ts +380 -0
- package/src/ui-layer.ts +83 -0
- package/src/ui-state.ts +220 -0
- package/src/version.ts +2 -0
- package/src/viewport.ts +253 -0
- package/src/warmup.ts +1357 -0
- package/src/water-surface.ts +384 -0
- package/src/wave-field.ts +524 -0
- package/src/world-capabilities.ts +131 -0
- package/src/world-cell-proxy.ts +392 -0
- package/src/world-cells.ts +10564 -0
- package/src/world-gpu-scene.ts +3354 -0
- package/src/world-heightmap.ts +82 -0
- package/src/world-package.ts +469 -0
- package/src/world-passes.ts +582 -0
- package/src/world-region.ts +17 -0
- package/src/world-terrain-splat.ts +564 -0
- package/src/world-tiles.ts +3826 -0
- package/src/world-topology.ts +370 -0
- package/src/world-validate.ts +48 -0
- 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
|
+
}
|