@threenative/core 0.3.11 → 0.3.13
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/README.md +1 -1
- package/capabilities.json +1988 -204
- package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
- package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
- package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
- package/dist/chunk-4SRAQFTU.js +133 -0
- package/dist/chunk-CFGTPFUH.js +231 -0
- package/dist/chunk-DIPIJICH.js +8916 -0
- package/dist/chunk-EEABDLUC.js +2237 -0
- package/dist/chunk-EFWZWLPY.js +1895 -0
- package/dist/chunk-GXY7B3JG.js +46 -0
- package/dist/chunk-GYUZJQ7U.js +280 -0
- package/dist/chunk-H4J6IAJE.js +504 -0
- package/dist/chunk-KIRUKTBQ.js +187 -0
- package/dist/chunk-QWJEMUUT.js +94 -0
- package/dist/chunk-SV4QVUTQ.js +31 -0
- package/dist/chunk-U4YHUKKL.js +615 -0
- package/dist/chunk-VP43GIWW.js +18 -0
- package/dist/chunk-XDTZ4QMO.js +160 -0
- package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
- package/dist/{game-DzMcitDO.d.ts → game-k8K3hZai.d.ts} +85 -9
- package/dist/hot.d.ts +5 -4
- package/dist/hot.js +5 -52
- package/dist/index.d.ts +633 -1351
- package/dist/index.js +12873 -23068
- package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-DPTzeCcD.d.ts} +35 -3
- package/dist/playtest.d.ts +5 -4
- package/dist/playtest.js +25 -75
- package/dist/quality-BYqKGAwo.d.ts +868 -0
- package/dist/react-css.js +1 -215
- package/dist/react.d.ts +3 -2
- package/dist/render-environment.d.ts +170 -0
- package/dist/render-environment.js +352 -0
- package/dist/{renderer-rZm0hVqq.d.ts → renderer-BtOSseYf.d.ts} +42 -35
- package/dist/spells/index.d.ts +643 -0
- package/dist/spells/index.js +1558 -0
- package/dist/spells/ultra/index.d.ts +1600 -0
- package/dist/spells/ultra/index.js +6804 -0
- package/dist/terrain-jobs-worker.js +1 -123
- package/dist/two-sided-foliage-W523J3UM.js +1 -0
- package/dist/ui-layer.js +6 -384
- package/dist/worker.js +13 -43
- package/dist/world.d.ts +988 -268
- package/dist/world.js +17464 -18290
- package/mcp/animation-server.mjs +1 -1
- package/mcp/animation.mjs +2 -3
- package/mcp/engine-server.mjs +245 -52
- package/mcp/servers.mjs +10 -3
- package/mcp/terrain.mjs +8 -0
- package/package.json +19 -7
- package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
- package/patches/three@0.187.0.patch +2004 -407
- package/src/animation-batch.ts +193 -0
- package/src/animation-layers.ts +7 -3
- package/src/animation.ts +209 -29
- package/src/asset-cache.ts +3 -3
- package/src/asset-memo.ts +202 -0
- package/src/assets.ts +437 -125
- package/src/auto-batch.ts +190 -44
- package/src/card-lod.ts +152 -0
- package/src/compressed-texture-preparation.ts +1008 -0
- package/src/compute-driven.ts +1 -1
- package/src/config.ts +8 -0
- package/src/debug.ts +103 -22
- package/src/dev-global.ts +54 -0
- package/src/engine-hooks.ts +37 -0
- package/src/frame-budget.ts +50 -23
- package/src/game-boot-phase.ts +269 -0
- package/src/game-dev-tools.ts +86 -0
- package/src/game-frame-loop.ts +958 -0
- package/src/game-renderer-metrics.ts +77 -0
- package/src/game-startup.ts +1076 -0
- package/src/game-ui.ts +84 -0
- package/src/game-validate.ts +70 -0
- package/src/game.ts +198 -2264
- package/src/gamepad-mappings.ts +269 -0
- package/src/generated/console-markers.ts +13 -0
- package/src/geometry-capture.ts +28 -4
- package/src/gpu-readings.ts +98 -0
- package/src/gpu-scene-bvh.ts +149 -36
- package/src/hot.ts +4 -7
- package/src/index.ts +141 -9
- package/src/input.ts +237 -25
- package/src/instanced-batch-lod.ts +3 -8
- package/src/interpolation.ts +171 -40
- package/src/launch-diagnostics.ts +22 -12
- package/src/look/ao-admission.ts +25 -0
- package/src/look/auto-exposure.ts +5 -16
- package/src/look/default-tone-mapping.ts +41 -5
- package/src/look/filmic-tone-mapping.ts +15 -13
- package/src/look/local-exposure.ts +2 -7
- package/src/look/look-diagnostics.ts +3 -3
- package/src/look/quad-pass.ts +21 -0
- package/src/look/quality.ts +14 -5
- package/src/look/unreal-bloom.ts +4 -13
- package/src/look/world-environment.ts +113 -103
- package/src/loop.ts +29 -0
- package/src/merge-parts.ts +20 -24
- package/src/model-lod.ts +139 -17
- package/src/particle-kinds.ts +515 -0
- package/src/particle-significance.ts +12 -0
- package/src/particles.ts +19 -10
- package/src/picking.ts +17 -3
- package/src/platform.ts +23 -4
- package/src/playtest.ts +27 -1
- package/src/profiling/FrameStages.ts +5 -6
- package/src/profiling/Spans.ts +3 -17
- package/src/profiling/debug-telemetry.ts +2 -6
- package/src/profiling/render-list-validate.ts +6 -15
- package/src/projection-apply.ts +4 -1
- package/src/projection-marker.ts +2 -1
- package/src/projection-plan.ts +9 -6
- package/src/quiet-markers.ts +3 -10
- package/src/render/cpu-bvh.ts +100 -0
- package/src/render/depth-pyramid.ts +6 -14
- package/src/render/environment/environmentContribution.ts +202 -0
- package/src/render/environment/environmentRadiance.ts +44 -0
- package/src/render/environment/environmentSampleCache.ts +56 -0
- package/src/render/environment/environmentSampling.ts +201 -0
- package/src/render/environment/environmentSnapshot.ts +71 -0
- package/src/render/environment/gate.ts +57 -0
- package/src/render/mesh-pool.ts +4 -20
- package/src/render/probe-trace.ts +872 -0
- package/src/render/probe-volume.ts +780 -34
- package/src/render/radiance-cache.ts +17 -0
- package/src/render/resolution-subrect.ts +2 -0
- package/src/render/rough-diffuse.ts +46 -12
- package/src/render/soft-shadow.ts +27 -12
- package/src/render/virtual-shadow-adaptive.ts +55 -0
- package/src/render/virtual-shadow-casters.ts +175 -0
- package/src/render/virtual-shadow-layers.ts +76 -0
- package/src/render/virtual-shadow-level.ts +224 -0
- package/src/render/virtual-shadow-markers.ts +193 -0
- package/src/render/virtual-shadow-options.ts +370 -0
- package/src/render/virtual-shadow-pages.ts +5 -0
- package/src/render/virtual-shadow-partial.ts +13 -0
- package/src/render/virtual-shadow.ts +231 -1008
- package/src/render/world-impostor-surface.ts +402 -40
- package/src/render/world-impostor.ts +5 -2
- package/src/render-camera-cull.ts +98 -3
- package/src/render-environment.ts +41 -0
- package/src/render-pass-budget.ts +34 -7
- package/src/renderProjection.ts +22 -0
- package/src/renderer-config.ts +36 -0
- package/src/renderer-facts.ts +37 -0
- package/src/renderer.ts +144 -65
- package/src/resolution-scaler.ts +3 -2
- package/src/scene-entry-inspectors.ts +61 -0
- package/src/snow-field.ts +2 -1
- package/src/spells/cast-pool.ts +361 -0
- package/src/spells/index.ts +177 -0
- package/src/spells/mechanisms.ts +295 -0
- package/src/spells/reaction-field.ts +415 -0
- package/src/spells/spell-lights.ts +139 -0
- package/src/spells/spell-world.ts +187 -0
- package/src/spells/spell.ts +397 -0
- package/src/spells/spells.ts +283 -0
- package/src/spells/ultra/engine/camera.ts +184 -0
- package/src/spells/ultra/engine/quality.ts +96 -0
- package/src/spells/ultra/index.ts +52 -0
- package/src/spells/ultra/main.ts +305 -0
- package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
- package/src/spells/ultra/spells/cast.ts +233 -0
- package/src/spells/ultra/spells/fire.ts +1267 -0
- package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
- package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
- package/src/spells/ultra/vfx/FxTarget.ts +61 -0
- package/src/spells/ultra/vfx/GroundField.ts +1399 -0
- package/src/spells/ultra/vfx/Particles.ts +1475 -0
- package/src/spells/ultra/vfx/Ribbons.ts +645 -0
- package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
- package/src/spells/ultra/vfx/Volumes.ts +489 -0
- package/src/spells/ultra/vfx/common.ts +1195 -0
- package/src/spells/ultra/vfx/noise.ts +441 -0
- package/src/startup-offscreen-bytes.ts +78 -0
- package/src/startup-readiness.ts +128 -34
- package/src/static-transform.ts +25 -19
- package/src/streamed-textures.ts +112 -0
- package/src/streaming.ts +68 -4
- package/src/texture-streaming.ts +331 -0
- package/src/version.ts +1 -1
- package/src/warmup.ts +56 -8
- package/src/water-surface.ts +9 -3
- package/src/worker.ts +12 -2
- package/src/world-bundle-safety.ts +446 -0
- package/src/world-cell-batches.ts +1178 -0
- package/src/world-cell-chunks.ts +1128 -0
- package/src/world-cell-data.ts +995 -0
- package/src/world-cell-impostors.ts +1461 -0
- package/src/world-cell-lod-bias.ts +151 -0
- package/src/world-cell-models.ts +1074 -0
- package/src/world-cell-options.ts +177 -0
- package/src/world-cell-placements.ts +798 -0
- package/src/world-cell-prewarm.ts +592 -0
- package/src/world-cell-readiness.ts +357 -0
- package/src/world-cell-records.ts +401 -0
- package/src/world-cell-render-bundles.ts +459 -0
- package/src/world-cell-render-gpu-dress.ts +710 -0
- package/src/world-cell-render-main-cull.ts +540 -0
- package/src/world-cell-render-shadow-claims.ts +198 -0
- package/src/world-cell-render-util.ts +259 -0
- package/src/world-cell-render.ts +1501 -0
- package/src/world-cell-residency.ts +754 -0
- package/src/world-cell-stale.ts +238 -0
- package/src/world-cells.ts +1335 -10418
- package/src/world-chunk-shadow.ts +308 -0
- package/src/world-collar.ts +315 -0
- package/src/world-gpu-flags.ts +131 -0
- package/src/world-gpu-readback.ts +881 -0
- package/src/world-gpu-reference.ts +524 -0
- package/src/world-gpu-scene.ts +256 -2286
- package/src/world-gpu-shadow.ts +203 -0
- package/src/world-gpu-types.ts +409 -0
- package/src/world-gpu-validation.ts +518 -0
- package/src/world-heightfield.ts +802 -0
- package/src/world-load-limiter.ts +111 -0
- package/src/world-model-sections.ts +80 -0
- package/src/world-noise.ts +241 -0
- package/src/world-package.ts +42 -0
- package/src/world-region.ts +1 -1
- package/src/world-river-ribbon.ts +282 -0
- package/src/world-root-frame.ts +39 -0
- package/src/world-shore-field.ts +91 -0
- package/src/world-static-pose.ts +163 -0
- package/src/world-surface-sampler.ts +48 -0
- package/src/world-terrain-splat.ts +361 -153
- package/src/world-tile-budget.ts +249 -0
- package/src/world-tile-geometry.ts +469 -0
- package/src/world-tile-lod.ts +408 -0
- package/src/world-tile-observation.ts +566 -0
- package/src/world-tile-stitch.ts +166 -0
- package/src/world-tiles.ts +247 -1755
- package/src/world-validate.ts +6 -14
- package/src/world-warm.ts +51 -0
- package/src/world-water-bodies.ts +359 -0
- package/src/world.ts +48 -741
|
@@ -0,0 +1,446 @@
|
|
|
1
|
+
import { type Material, type Mesh, Object3D } from "three";
|
|
2
|
+
import { isEngineRenderHook } from "./engine-render-hook.js";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* The value `NodeUpdateType.RENDER` has, read as text so this file needs no import for it: a node
|
|
6
|
+
* whose `updateBefore` runs on every render is a node whose work happens inside the draw that
|
|
7
|
+
* recorded it, which is the whole test.
|
|
8
|
+
*/
|
|
9
|
+
const PER_RENDER_UPDATE = "render";
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Whether a node graph copies or renders the framebuffer, which a bundle encoder cannot be asked for.
|
|
13
|
+
*
|
|
14
|
+
* Every such node does its work in `updateBefore` and every one of them touches the *current* render
|
|
15
|
+
* pass: `ViewportTextureNode` copies the bound framebuffer into a texture, and transmission, an
|
|
16
|
+
* `RTTNode`, a `ReflectorNode` or a `PassNode` renders into one. Recorded into a bundle, the current
|
|
17
|
+
* pass is a `GPURenderBundleEncoder`, which has no `end()` to close and no framebuffer to read, so
|
|
18
|
+
* the call throws `currentPass.end is not a function` from inside the record and takes the whole
|
|
19
|
+
* bundle's frame with it.
|
|
20
|
+
*
|
|
21
|
+
* Structural, over own properties and plain sub-objects, because a material's slots are node graphs
|
|
22
|
+
* rather than one node: a `viewportSharedTexture()` under an arithmetic chain is still this. What it
|
|
23
|
+
* cannot see is a node hidden inside an `Fn` body, which is how three keeps its own transmission
|
|
24
|
+
* sampler — hence `transmission` is asked of the material itself as well.
|
|
25
|
+
*/
|
|
26
|
+
interface IBundleGraphSnapshot {
|
|
27
|
+
readonly node: object;
|
|
28
|
+
readonly keys: readonly string[];
|
|
29
|
+
readonly links: readonly unknown[];
|
|
30
|
+
readonly isNode: unknown;
|
|
31
|
+
readonly beforeType: unknown;
|
|
32
|
+
readonly before: string;
|
|
33
|
+
readonly version: unknown;
|
|
34
|
+
readonly terminal: boolean;
|
|
35
|
+
readonly childReader: unknown;
|
|
36
|
+
readonly children: readonly object[] | undefined;
|
|
37
|
+
}
|
|
38
|
+
interface IBundleGraphCapture {
|
|
39
|
+
readonly rows: IBundleGraphSnapshot[];
|
|
40
|
+
links: number;
|
|
41
|
+
overflow: boolean;
|
|
42
|
+
}
|
|
43
|
+
interface IBundleMaterialCheck {
|
|
44
|
+
readonly safe: boolean;
|
|
45
|
+
readonly revision: number;
|
|
46
|
+
readonly version: number;
|
|
47
|
+
readonly transparent: boolean;
|
|
48
|
+
readonly visible: boolean;
|
|
49
|
+
readonly transmission: unknown;
|
|
50
|
+
readonly rows: readonly IBundleGraphSnapshot[];
|
|
51
|
+
/** The frame whose deep validation (or fresh walk) last proved this verdict. */
|
|
52
|
+
provedFrame: number;
|
|
53
|
+
/** The last frame that tested this material, so a frame counts its rows once. */
|
|
54
|
+
testedFrame: number;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Deep snapshot rows proved per frame, across every material. A small world proves every graph on
|
|
59
|
+
* every frame; a forest of ~50 foliage surfaces at ~1,000 rows each spreads its proof instead of
|
|
60
|
+
* walking ~50,000 rows each frame, which measured 10.9 s of a 25 s trace on the Strata preview. A
|
|
61
|
+
* row measured ~2.7 µs on a real display (NVIDIA Turing), so the budget is under a millisecond.
|
|
62
|
+
*/
|
|
63
|
+
const BUNDLE_PROOF_ROWS_PER_FRAME = 256;
|
|
64
|
+
/**
|
|
65
|
+
* The longest proof period, whatever the load: ten seconds at 60 Hz. Three recompiles a draw only
|
|
66
|
+
* when `material.version` moves, so a deep edit without `needsUpdate` changes no drawn pipeline in
|
|
67
|
+
* that window; the proof only withdraws a bundle the edit made unsafe. A 60-frame cap measured
|
|
68
|
+
* ~3 ms a frame on the Strata forest's ~70,000 rows.
|
|
69
|
+
*/
|
|
70
|
+
const BUNDLE_PROOF_MAX_PERIOD = 600;
|
|
71
|
+
|
|
72
|
+
/** The owned engine's witness of each proved material's surface flags (PRD-879). */
|
|
73
|
+
interface IMaterialWitnessHost {
|
|
74
|
+
__tnMaterialWatch?(materials: readonly Material[]): number;
|
|
75
|
+
__tnMaterialCheck?(): ArrayLike<number>;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** Own-link and installed-Node child snapshots avoid inherited TSL method scans. Deep unversioned
|
|
79
|
+
* edits still invalidate: version/root identity alone cannot certify a mutable node graph. The
|
|
80
|
+
* shallow witness (version, transparency, visibility, transmission) holds on every check: read per
|
|
81
|
+
* check, or for a `deep: false` check the flags are the owned engine's one answer a frame. The deep
|
|
82
|
+
* rows are proved once per `staleFrames` period: the rows the last frame tested over a per-frame
|
|
83
|
+
* budget, so a small world proves every frame and a forest spreads its proofs evenly, each material
|
|
84
|
+
* in its own slot of the period. Three itself rebuilds a draw only when `material.version` moves
|
|
85
|
+
* (`RenderObjects.get`), so a deep edit without `needsUpdate` changes no compiled draw inside that
|
|
86
|
+
* window. A graph past the witness caps uses the uncached safety walk. */
|
|
87
|
+
export class BundleSurfaceSafety {
|
|
88
|
+
#checks = new WeakMap<Material, IBundleMaterialCheck>();
|
|
89
|
+
/**
|
|
90
|
+
* The owned engine holds every cached verdict's `transparent`, `visible` and `transmission` and
|
|
91
|
+
* answers which moved in one call a frame, so a settled `deep: false` test reads none of them.
|
|
92
|
+
* Upstream three has no such host method and reads them per test, as before.
|
|
93
|
+
*
|
|
94
|
+
* ponytail: the list keeps every proved material until `clear`, which a world bounds by its assets.
|
|
95
|
+
*/
|
|
96
|
+
readonly #witness = new Object3D() as Object3D & IMaterialWitnessHost;
|
|
97
|
+
#witnessed: Material[] = [];
|
|
98
|
+
readonly #moved = new Set<Material>();
|
|
99
|
+
#revision = 0;
|
|
100
|
+
#frame = 0;
|
|
101
|
+
#frameRows = 0;
|
|
102
|
+
readonly stats = {
|
|
103
|
+
checks: 0,
|
|
104
|
+
refreshes: 0,
|
|
105
|
+
validations: 0,
|
|
106
|
+
uncached: 0,
|
|
107
|
+
deferred: 0,
|
|
108
|
+
staleFrames: 1,
|
|
109
|
+
};
|
|
110
|
+
|
|
111
|
+
clear(): void {
|
|
112
|
+
this.#checks = new WeakMap();
|
|
113
|
+
this.#witnessed = [];
|
|
114
|
+
this.#moved.clear();
|
|
115
|
+
this.#witness.__tnMaterialWatch?.(this.#witnessed);
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/** Opens a frame: the period every deep proof is spread over follows the last frame's rows. */
|
|
119
|
+
beginFrame(): void {
|
|
120
|
+
this.#frame++;
|
|
121
|
+
this.stats.staleFrames = Math.min(
|
|
122
|
+
BUNDLE_PROOF_MAX_PERIOD,
|
|
123
|
+
Math.max(1, Math.ceil(this.#frameRows / BUNDLE_PROOF_ROWS_PER_FRAME)),
|
|
124
|
+
);
|
|
125
|
+
this.#frameRows = 0;
|
|
126
|
+
// A moved material stays moved until its next test re-proves it, because that re-proof
|
|
127
|
+
// re-stamps the whole list and the engine would not answer for it again.
|
|
128
|
+
const moved = this.#witness.__tnMaterialCheck?.();
|
|
129
|
+
if (moved !== undefined)
|
|
130
|
+
for (let at = 0; at < moved.length; at++)
|
|
131
|
+
this.#moved.add(this.#witnessed[moved[at] as number] as Material);
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/**
|
|
135
|
+
* `deep: false` is for a renderer that records its own bundles from each frame's draws (the owned
|
|
136
|
+
* engine, PRD-754): it never replays three's recorded render objects, so a deep node edit cannot
|
|
137
|
+
* reach a stale record there and only the shallow witness re-checks. On the Wasm facade every
|
|
138
|
+
* deep row read crosses into the engine, which made the proof ~1 ms a walked frame.
|
|
139
|
+
*/
|
|
140
|
+
test(material: Material, deep = true): IBundleMaterialCheck {
|
|
141
|
+
this.stats.checks++;
|
|
142
|
+
const previous = this.#checks.get(material);
|
|
143
|
+
if (previous !== undefined && this.#shallowHolds(material, previous, deep)) {
|
|
144
|
+
if (!deep) return previous;
|
|
145
|
+
if (previous.testedFrame !== this.#frame) {
|
|
146
|
+
previous.testedFrame = this.#frame;
|
|
147
|
+
this.#frameRows += previous.rows.length;
|
|
148
|
+
}
|
|
149
|
+
if (previous.provedFrame === this.#frame) return previous;
|
|
150
|
+
const period = this.stats.staleFrames;
|
|
151
|
+
const stale = this.#frame - previous.provedFrame;
|
|
152
|
+
// Each verdict proves in its own slot of the period; a slot missed while the period grew is
|
|
153
|
+
// made up at twice the period, so no verdict waits longer than that.
|
|
154
|
+
if ((this.#frame + previous.revision) % period !== 0 && stale < 2 * period) {
|
|
155
|
+
this.stats.deferred++;
|
|
156
|
+
return previous;
|
|
157
|
+
}
|
|
158
|
+
if (previous.rows.every(graphSnapshotCurrent)) {
|
|
159
|
+
this.stats.validations++;
|
|
160
|
+
previous.provedFrame = this.#frame;
|
|
161
|
+
return previous;
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
this.stats.refreshes++;
|
|
165
|
+
const capture: IBundleGraphCapture = { rows: [], links: 0, overflow: false };
|
|
166
|
+
const checked: IBundleMaterialCheck = {
|
|
167
|
+
safe: bundleSafeMaterial(material, capture),
|
|
168
|
+
revision: ++this.#revision,
|
|
169
|
+
version: material.version,
|
|
170
|
+
transparent: material.transparent,
|
|
171
|
+
visible: material.visible,
|
|
172
|
+
transmission: Reflect.get(material, "transmission"),
|
|
173
|
+
rows: capture.rows,
|
|
174
|
+
provedFrame: this.#frame,
|
|
175
|
+
testedFrame: this.#frame,
|
|
176
|
+
};
|
|
177
|
+
if (capture.overflow) {
|
|
178
|
+
this.stats.uncached++;
|
|
179
|
+
this.#checks.delete(material);
|
|
180
|
+
} else {
|
|
181
|
+
this.#checks.set(material, checked);
|
|
182
|
+
this.#rewatch(material);
|
|
183
|
+
}
|
|
184
|
+
return checked;
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* Whether the material still holds the cached verdict's shallow witness. `version` is JS-side;
|
|
189
|
+
* the flags are the engine's answer when it witnesses them and a `deep: false` test asks.
|
|
190
|
+
*/
|
|
191
|
+
#shallowHolds(material: Material, previous: IBundleMaterialCheck, deep: boolean): boolean {
|
|
192
|
+
if (previous.version !== material.version) return false;
|
|
193
|
+
if (!deep && this.#witness.__tnMaterialCheck !== undefined) return !this.#moved.has(material);
|
|
194
|
+
return (
|
|
195
|
+
previous.transparent === material.transparent &&
|
|
196
|
+
previous.visible === material.visible &&
|
|
197
|
+
previous.transmission === Reflect.get(material, "transmission")
|
|
198
|
+
);
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
/** Re-stamp the engine's witness after a verdict was (re)taken, so it answers from this state. */
|
|
202
|
+
#rewatch(material: Material): void {
|
|
203
|
+
if (this.#witness.__tnMaterialWatch === undefined) return;
|
|
204
|
+
if (!this.#witnessed.includes(material)) this.#witnessed.push(material);
|
|
205
|
+
this.#moved.delete(material);
|
|
206
|
+
this.#witness.__tnMaterialWatch(this.#witnessed);
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
function graphSnapshotCurrent(row: IBundleGraphSnapshot): boolean {
|
|
211
|
+
const node = row.node;
|
|
212
|
+
const before = typeof Reflect.get(node, "updateBefore");
|
|
213
|
+
if (
|
|
214
|
+
Reflect.get(node, "isNode") !== row.isNode ||
|
|
215
|
+
Reflect.get(node, "updateBeforeType") !== row.beforeType ||
|
|
216
|
+
before !== row.before ||
|
|
217
|
+
Reflect.get(node, "version") !== row.version
|
|
218
|
+
)
|
|
219
|
+
return false;
|
|
220
|
+
if (row.terminal) return true; // Still a framebuffer reader, whatever its other children do.
|
|
221
|
+
// TSL prototypes carry thousands of enumerable chaining methods, which are not child links.
|
|
222
|
+
// Own slots stay cheap; Three's actual child reader witnesses inherited container links below.
|
|
223
|
+
const keys = bundleGraphKeys(node);
|
|
224
|
+
if (keys.length !== row.keys.length) return false;
|
|
225
|
+
for (let index = 0; index < keys.length; index++) {
|
|
226
|
+
const key = keys[index] as string;
|
|
227
|
+
if (row.keys[index] !== key) return false;
|
|
228
|
+
const value = Reflect.get(node, key);
|
|
229
|
+
if ((value !== null && typeof value === "object" ? value : undefined) !== row.links[index])
|
|
230
|
+
return false;
|
|
231
|
+
}
|
|
232
|
+
const reader = bundleGraphChildReader(node);
|
|
233
|
+
if (reader !== row.childReader) return false;
|
|
234
|
+
const expected = row.children;
|
|
235
|
+
if (expected === undefined) return false;
|
|
236
|
+
return readBundleGraphChildren(node, reader, expected) === expected;
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
/**
|
|
240
|
+
* Three reads non-enumerable own Node/Material slots, but never inherited TSL chain methods, and
|
|
241
|
+
* never a `_`-prefixed slot: `Node._getChildren` skips those, because they are private caches
|
|
242
|
+
* (`ScreenNode._output` is rewritten every frame) rather than graph structure.
|
|
243
|
+
*/
|
|
244
|
+
function bundleGraphKeys(node: object): string[] {
|
|
245
|
+
return (
|
|
246
|
+
Reflect.get(node, "isNode") === true || Reflect.get(node, "isMaterial") === true
|
|
247
|
+
? Object.getOwnPropertyNames(node)
|
|
248
|
+
: Object.keys(node)
|
|
249
|
+
).filter((key) => !key.startsWith("_"));
|
|
250
|
+
}
|
|
251
|
+
function bundleGraphChildReader(node: object): unknown {
|
|
252
|
+
return Reflect.get(node, "isNode") === true ? Reflect.get(node, "getChildren") : undefined;
|
|
253
|
+
}
|
|
254
|
+
/** A child three's `getChildren` yields: an object node, or a callable TSL `Fn` (`typeof` "function"). */
|
|
255
|
+
function isGraphNode(child: unknown): child is object {
|
|
256
|
+
return (
|
|
257
|
+
child !== null &&
|
|
258
|
+
(typeof child === "object" || typeof child === "function") &&
|
|
259
|
+
Reflect.get(child, "isNode") === true
|
|
260
|
+
);
|
|
261
|
+
}
|
|
262
|
+
function readBundleGraphChildren(
|
|
263
|
+
node: object,
|
|
264
|
+
reader: unknown,
|
|
265
|
+
expected?: readonly object[],
|
|
266
|
+
): readonly object[] | undefined {
|
|
267
|
+
if (reader === undefined) {
|
|
268
|
+
if (expected === undefined) return [];
|
|
269
|
+
return expected.length === 0 ? expected : undefined;
|
|
270
|
+
}
|
|
271
|
+
if (typeof reader !== "function") return undefined;
|
|
272
|
+
try {
|
|
273
|
+
const result: unknown = reader.call(node);
|
|
274
|
+
if (
|
|
275
|
+
result === null ||
|
|
276
|
+
typeof result !== "object" ||
|
|
277
|
+
typeof Reflect.get(result, Symbol.iterator) !== "function"
|
|
278
|
+
)
|
|
279
|
+
return undefined;
|
|
280
|
+
if (expected !== undefined) {
|
|
281
|
+
let index = 0;
|
|
282
|
+
let match = true;
|
|
283
|
+
for (const child of result as Iterable<unknown>) {
|
|
284
|
+
if (index >= 8192 || !isGraphNode(child)) return undefined;
|
|
285
|
+
if (match && child !== expected[index]) match = false;
|
|
286
|
+
index++;
|
|
287
|
+
}
|
|
288
|
+
return match && index === expected.length ? expected : undefined;
|
|
289
|
+
}
|
|
290
|
+
const children: object[] = [];
|
|
291
|
+
for (const child of result as Iterable<unknown>) {
|
|
292
|
+
if (children.length >= 8192 || !isGraphNode(child)) return undefined;
|
|
293
|
+
children.push(child);
|
|
294
|
+
}
|
|
295
|
+
return children;
|
|
296
|
+
} catch {
|
|
297
|
+
return undefined;
|
|
298
|
+
}
|
|
299
|
+
}
|
|
300
|
+
function captureBundleGraph(
|
|
301
|
+
node: object,
|
|
302
|
+
terminal: boolean,
|
|
303
|
+
capture: IBundleGraphCapture,
|
|
304
|
+
childReader: unknown,
|
|
305
|
+
children: readonly object[] | undefined,
|
|
306
|
+
): readonly unknown[] {
|
|
307
|
+
const keys = terminal ? [] : bundleGraphKeys(node);
|
|
308
|
+
const count = keys.length;
|
|
309
|
+
capture.links += count + (children?.length ?? 0);
|
|
310
|
+
if (children === undefined) capture.overflow = true;
|
|
311
|
+
// A shipped foliage surface reaches ~1,000 nodes and ~21,000 links; a cap below that re-walked and
|
|
312
|
+
// re-recorded every such material on every frame. The witness holds references only.
|
|
313
|
+
if (capture.rows.length >= 4096 || capture.links > 65_536) capture.overflow = true;
|
|
314
|
+
const values: unknown[] = new Array(count);
|
|
315
|
+
if (capture.overflow) {
|
|
316
|
+
for (let index = 0; index < count; index++)
|
|
317
|
+
values[index] = Reflect.get(node, keys[index] as string);
|
|
318
|
+
return values;
|
|
319
|
+
}
|
|
320
|
+
const links: (object | undefined)[] = new Array(count);
|
|
321
|
+
for (let index = 0; index < count; index++) {
|
|
322
|
+
const value: unknown = Reflect.get(node, keys[index] as string);
|
|
323
|
+
values[index] = value;
|
|
324
|
+
links[index] = value !== null && typeof value === "object" ? value : undefined;
|
|
325
|
+
}
|
|
326
|
+
capture.rows.push({
|
|
327
|
+
node,
|
|
328
|
+
terminal,
|
|
329
|
+
childReader,
|
|
330
|
+
children,
|
|
331
|
+
keys,
|
|
332
|
+
links,
|
|
333
|
+
isNode: Reflect.get(node, "isNode"),
|
|
334
|
+
beforeType: Reflect.get(node, "updateBeforeType"),
|
|
335
|
+
before: typeof Reflect.get(node, "updateBefore"),
|
|
336
|
+
version: Reflect.get(node, "version"),
|
|
337
|
+
});
|
|
338
|
+
return values;
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
function samplesFramebuffer(
|
|
342
|
+
node: unknown,
|
|
343
|
+
seen: Set<unknown>,
|
|
344
|
+
capture?: IBundleGraphCapture,
|
|
345
|
+
): boolean {
|
|
346
|
+
// Pixels and vertex data hold no node, and Object.values would copy every element of them.
|
|
347
|
+
if (node === null || typeof node !== "object" || ArrayBuffer.isView(node) || seen.has(node))
|
|
348
|
+
return false;
|
|
349
|
+
seen.add(node);
|
|
350
|
+
// A uniform group is a binding group, never a framebuffer reader, and three's shared frame and
|
|
351
|
+
// render groups bump their `version` on every frame (`UniformGroupNode.update`). Walking into one
|
|
352
|
+
// made every graph that holds a uniform look edited on every frame, which re-walked the whole
|
|
353
|
+
// graph and re-recorded its bundle each frame.
|
|
354
|
+
if (Reflect.get(node, "isUniformGroup") === true) return false;
|
|
355
|
+
const candidate = node as {
|
|
356
|
+
readonly isNode?: boolean;
|
|
357
|
+
readonly updateBefore?: unknown;
|
|
358
|
+
readonly updateBeforeType?: unknown;
|
|
359
|
+
};
|
|
360
|
+
if (
|
|
361
|
+
candidate.isNode === true &&
|
|
362
|
+
typeof candidate.updateBefore === "function" &&
|
|
363
|
+
candidate.updateBeforeType === PER_RENDER_UPDATE
|
|
364
|
+
) {
|
|
365
|
+
if (capture !== undefined) captureBundleGraph(node, true, capture, undefined, []);
|
|
366
|
+
return true;
|
|
367
|
+
}
|
|
368
|
+
// getChildren owns Three's non-enumerable, dictionary and sparse-array child semantics. Its
|
|
369
|
+
// ordered identities are a live witness, including prototype edits with unchanged own keys.
|
|
370
|
+
const reader = bundleGraphChildReader(node);
|
|
371
|
+
const children = readBundleGraphChildren(node, reader);
|
|
372
|
+
const values =
|
|
373
|
+
capture === undefined
|
|
374
|
+
? bundleGraphKeys(node).map((key) => Reflect.get(node, key))
|
|
375
|
+
: captureBundleGraph(node, false, capture, reader, children);
|
|
376
|
+
// Malformed/oversized child output retains the live source path. The stored witness is capped;
|
|
377
|
+
// Three's eager getChildren implementation can still scan an authored array before yielding.
|
|
378
|
+
if (children === undefined) return true;
|
|
379
|
+
for (const value of values) {
|
|
380
|
+
if (value === null || typeof value !== "object") continue;
|
|
381
|
+
if (samplesFramebuffer(value, seen, capture)) return true;
|
|
382
|
+
}
|
|
383
|
+
for (const child of children) {
|
|
384
|
+
if (samplesFramebuffer(child, seen, capture)) return true;
|
|
385
|
+
}
|
|
386
|
+
return false;
|
|
387
|
+
}
|
|
388
|
+
|
|
389
|
+
/**
|
|
390
|
+
* Whether one mesh's draw can be recorded into a bundle and replayed from it.
|
|
391
|
+
*
|
|
392
|
+
* A bundle is an encoder, not a render pass: three fixes its render list and its draw order when it
|
|
393
|
+
* records it, and every replay runs the encoded commands with no pass of its own to ask anything of.
|
|
394
|
+
* So a mesh is bundle-safe only when nothing about its draw needs a live pass — the one question
|
|
395
|
+
* {@link samplesFramebuffer} and the checks below both ask, of the node graph and of the object.
|
|
396
|
+
*
|
|
397
|
+
* - **The framebuffer.** A viewport or screen-space refraction sample, transmission, a render target,
|
|
398
|
+
* a reflector: `samplesFramebuffer`, plus `transmission` itself, which three's own lighting model
|
|
399
|
+
* reaches through an `Fn` body no structural walk can see.
|
|
400
|
+
* - **Per-frame order.** A transparent mesh is sorted against its neighbours every frame; a record
|
|
401
|
+
* froze that order when it was made, so a bundled one draws in the order it happened to be in.
|
|
402
|
+
* - **Per-object hooks.** `onBeforeRender`/`onAfterRender` are the two places a game reads the camera
|
|
403
|
+
* and the frame for a draw, and a replay runs them once at record time and never again. The
|
|
404
|
+
* engine's own borrow — the prewarm counting its batch's first submitted draw — is bookkeeping
|
|
405
|
+
* about the draw rather than a claim on the object, so it does not refuse; `isEngineRenderHook` is
|
|
406
|
+
* what tells them apart, the same answer `projection-plan.ts` gives.
|
|
407
|
+
* - **Per-frame vertices.** A skinned or morphed mesh's positions are posed per frame from bones the
|
|
408
|
+
* record never reads, so its encoded vertices are its rest pose forever.
|
|
409
|
+
*
|
|
410
|
+
* A mesh that fails this stays on the per-object path — the path every chunk drew before bundles
|
|
411
|
+
* existed — so a refusal costs the draw it was already paying and nothing else.
|
|
412
|
+
*/
|
|
413
|
+
export function bundleSafe(mesh: Mesh): boolean {
|
|
414
|
+
if (ownHook(mesh, "onBeforeRender")) return false;
|
|
415
|
+
if (ownHook(mesh, "onAfterRender")) return false;
|
|
416
|
+
if ((mesh as Mesh & { readonly isSkinnedMesh?: boolean }).isSkinnedMesh === true) return false;
|
|
417
|
+
if (mesh.morphTargetInfluences !== undefined) return false;
|
|
418
|
+
return (Array.isArray(mesh.material) ? mesh.material : [mesh.material]).every((material) =>
|
|
419
|
+
bundleSafeMaterial(material),
|
|
420
|
+
);
|
|
421
|
+
}
|
|
422
|
+
|
|
423
|
+
/**
|
|
424
|
+
* Whether this mesh carries a render hook of its own that is the game's, which a record freezes.
|
|
425
|
+
*
|
|
426
|
+
* `Object.hasOwn`, not the prototype comparison: the engine installs its own hook as an own property
|
|
427
|
+
* on the very batches a prewarm borrowed, and refusing those would keep every batch of a streamed
|
|
428
|
+
* world on the per-object path.
|
|
429
|
+
*/
|
|
430
|
+
export function ownHook(mesh: Mesh, name: "onAfterRender" | "onBeforeRender"): boolean {
|
|
431
|
+
return Object.hasOwn(mesh, name) && isEngineRenderHook(mesh[name]) === false;
|
|
432
|
+
}
|
|
433
|
+
|
|
434
|
+
/** The material half of {@link bundleSafe}: nothing it draws may need a pass it was recorded in. */
|
|
435
|
+
export function bundleSafeMaterial(
|
|
436
|
+
material: Material | undefined,
|
|
437
|
+
capture?: IBundleGraphCapture,
|
|
438
|
+
): boolean {
|
|
439
|
+
if (material === undefined) return true;
|
|
440
|
+
if (material.transparent === true) return false;
|
|
441
|
+
// Read structurally: a `MeshPhysicalMaterial` always has the number and nothing else does, and
|
|
442
|
+
// three's transmission sampler is not a node slot, so `transmission` is the only way to see it.
|
|
443
|
+
const transmission = Reflect.get(material, "transmission");
|
|
444
|
+
if (typeof transmission === "number" && transmission > 0) return false;
|
|
445
|
+
return samplesFramebuffer(material, new Set(), capture) === false;
|
|
446
|
+
}
|