@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,175 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The parity oracle for anything that stops recomputing a transform.
|
|
3
|
+
*
|
|
4
|
+
* A cache that is right on the scene you tested and wrong on the one you did not is worse than no
|
|
5
|
+
* cache, because it ships as a visual bug nobody can reproduce. This is the instrument that makes
|
|
6
|
+
* the difference falsifiable: with `TN_RENDERLIST_VALIDATE=1`, every frame recomputes every world
|
|
7
|
+
* matrix from the authored transforms, the long way, and compares it elementwise against the one
|
|
8
|
+
* the frame is about to draw with. The first disagreement throws, naming the object and the
|
|
9
|
+
* element, because a validation mode that logs and continues is a validation mode nobody reads.
|
|
10
|
+
*
|
|
11
|
+
* It is a validation mode, not a proof: it proves the frames it ran on. Run it on the scenes you
|
|
12
|
+
* care about, in CI, for as many frames as you can afford.
|
|
13
|
+
*
|
|
14
|
+
* Off by default and expensive by construction — it does the work it is checking, twice.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
import { Matrix4, type Object3D } from "three";
|
|
18
|
+
import { composeSilencedByFreeze, worldSilencedByFreeze } from "../static-transform.js";
|
|
19
|
+
|
|
20
|
+
/** Marker printed when the validator is installed, so a log says which mode produced it. */
|
|
21
|
+
export const RENDERLIST_VALIDATE_MARKER = "TN_RENDERLIST_VALIDATE";
|
|
22
|
+
|
|
23
|
+
/** The launch flag. */
|
|
24
|
+
export const RENDERLIST_VALIDATE_FLAG = "TN_RENDERLIST_VALIDATE";
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Elementwise tolerance.
|
|
28
|
+
*
|
|
29
|
+
* The recomputation multiplies the same matrices in the same order as three does, so an exact
|
|
30
|
+
* match is what a correct cache produces; the tolerance exists for the case where a game composed
|
|
31
|
+
* its own matrix in a different order and lands a unit in the last place away.
|
|
32
|
+
*/
|
|
33
|
+
const TOLERANCE = 1e-6;
|
|
34
|
+
|
|
35
|
+
/** Whether `TN_RENDERLIST_VALIDATE` asks for validation on this launch. */
|
|
36
|
+
export function renderListValidationRequested(): boolean {
|
|
37
|
+
const host = globalThis as {
|
|
38
|
+
process?: { env?: Record<string, unknown> };
|
|
39
|
+
__tnRenderListValidate?: unknown;
|
|
40
|
+
};
|
|
41
|
+
const fromEnv = host.process?.env?.[RENDERLIST_VALIDATE_FLAG];
|
|
42
|
+
if (typeof fromEnv === "string" && fromEnv !== "" && fromEnv !== "0" && fromEnv !== "false")
|
|
43
|
+
return true;
|
|
44
|
+
const query = globalThis.location?.search;
|
|
45
|
+
if (
|
|
46
|
+
typeof query === "string" &&
|
|
47
|
+
/[?&]tnRenderListValidate=(?!0(?:&|$))(?!false(?:&|$))[^&]/u.test(query)
|
|
48
|
+
)
|
|
49
|
+
return true;
|
|
50
|
+
const fromGlobal = host.__tnRenderListValidate;
|
|
51
|
+
return fromGlobal === true || fromGlobal === "1";
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** What one frame's check found. */
|
|
55
|
+
export interface IValidationReport {
|
|
56
|
+
/** Objects whose world matrix was recomputed and compared. */
|
|
57
|
+
readonly checked: number;
|
|
58
|
+
/** Objects skipped because they own their own world matrix; reported, never counted as checked. */
|
|
59
|
+
readonly gameOwned: number;
|
|
60
|
+
/** Frames validated so far. */
|
|
61
|
+
readonly frames: number;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
const expected = new Matrix4();
|
|
65
|
+
const local = new Matrix4();
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Recomputes every world matrix under `root` and throws on the first that disagrees.
|
|
69
|
+
*
|
|
70
|
+
* The recomputation is deliberately independent of the flags a freeze sets: it composes the local
|
|
71
|
+
* matrix from `position`/`quaternion`/`scale` when the object composes its own, uses the authored
|
|
72
|
+
* `matrix` when it does not, and multiplies by the parent's *recomputed* world matrix rather than
|
|
73
|
+
* the cached one — so an error at the top of a subtree cannot be hidden by a matching error
|
|
74
|
+
* underneath it.
|
|
75
|
+
*/
|
|
76
|
+
export function validateWorldMatrices(root: Object3D): { checked: number; gameOwned: number } {
|
|
77
|
+
let checked = 0;
|
|
78
|
+
let gameOwned = 0;
|
|
79
|
+
const walk = (object: Object3D, parentWorld: Matrix4 | undefined): void => {
|
|
80
|
+
// An object that owns its own world matrix is not something this may recompute.
|
|
81
|
+
// `matrixWorldAutoUpdate === false` is three's way of saying "I maintain this myself", and the
|
|
82
|
+
// engine's own render projection sets it across its mirror. Recomputing those from the parent
|
|
83
|
+
// chain reports every one of them stale — measured on a real game before this existed, as
|
|
84
|
+
// `Mesh (id 19) has a stale world matrix at element 0: drawing 1 where a full recompute gives
|
|
85
|
+
// 0.5695`. The static freeze is the one exception: it turned the compose off itself, so the
|
|
86
|
+
// authored transform is still the truth and checking the frozen matrix against it is the point.
|
|
87
|
+
const owned = !object.matrixWorldAutoUpdate && !worldSilencedByFreeze(object);
|
|
88
|
+
let basis: Matrix4;
|
|
89
|
+
if (owned) {
|
|
90
|
+
gameOwned += 1;
|
|
91
|
+
basis = object.matrixWorld;
|
|
92
|
+
} else {
|
|
93
|
+
// The authored transform is the reference for anything the freeze silenced, since a frozen
|
|
94
|
+
// object's `matrix` *is* the cache under test. For an object the game drives by writing
|
|
95
|
+
// `matrix`, the matrix is the authored transform.
|
|
96
|
+
if (object.matrixAutoUpdate || composeSilencedByFreeze(object))
|
|
97
|
+
local.compose(object.position, object.quaternion, object.scale);
|
|
98
|
+
else local.copy(object.matrix);
|
|
99
|
+
if (parentWorld === undefined) expected.copy(local);
|
|
100
|
+
else expected.multiplyMatrices(parentWorld, local);
|
|
101
|
+
const actual = object.matrixWorld.elements;
|
|
102
|
+
const wanted = expected.elements;
|
|
103
|
+
for (let element = 0; element < 16; element += 1) {
|
|
104
|
+
const difference = Math.abs((actual[element] ?? 0) - (wanted[element] ?? 0));
|
|
105
|
+
if (difference > TOLERANCE) {
|
|
106
|
+
// Enough to act on. A divergence that names only an element number sends a reader back
|
|
107
|
+
// to the debugger; the flags and the parent are what distinguish "the cache is stale"
|
|
108
|
+
// from "this object is driven by something the walk does not own".
|
|
109
|
+
const label = object.name === "" ? object.type : object.name;
|
|
110
|
+
const parent = object.parent;
|
|
111
|
+
const parentLabel =
|
|
112
|
+
parent === null ? "<root>" : parent.name === "" ? parent.type : parent.name;
|
|
113
|
+
throw new Error(
|
|
114
|
+
`${RENDERLIST_VALIDATE_MARKER}: ${label} (id ${object.id}) has a stale world matrix at element ${element}: drawing ${String(actual[element])} where a full recompute gives ${String(wanted[element])}. matrixAutoUpdate=${String(object.matrixAutoUpdate)} matrixWorldAutoUpdate=${String(object.matrixWorldAutoUpdate)} matrixWorldNeedsUpdate=${String(object.matrixWorldNeedsUpdate)} position=[${object.position.x},${object.position.y},${object.position.z}] parent=${parentLabel} parentAuto=${parent === null ? "n/a" : String(parent.matrixWorldAutoUpdate)}`,
|
|
115
|
+
);
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
checked += 1;
|
|
119
|
+
basis = expected;
|
|
120
|
+
}
|
|
121
|
+
if (object.children.length === 0) return;
|
|
122
|
+
// The basis has to survive the recursion and there is one scratch matrix; copying it per level
|
|
123
|
+
// costs 16 writes and keeps the check independent of the cache it is checking.
|
|
124
|
+
const parentForChildren = new Matrix4().copy(basis);
|
|
125
|
+
for (const child of object.children) walk(child, parentForChildren);
|
|
126
|
+
};
|
|
127
|
+
walk(root, root.parent === null ? undefined : root.parent.matrixWorld);
|
|
128
|
+
return { checked, gameOwned };
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* The per-frame validator, installed when the flag asks for it.
|
|
133
|
+
*
|
|
134
|
+
* Holds a frame counter so the marker can say how much was proven, which is the difference between
|
|
135
|
+
* "validation passed" and "validation passed on 1,800 frames of the reference game".
|
|
136
|
+
*/
|
|
137
|
+
export class RenderListValidator {
|
|
138
|
+
#frames = 0;
|
|
139
|
+
#checked = 0;
|
|
140
|
+
#gameOwned = 0;
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Validates one frame. Throws on the first divergence.
|
|
144
|
+
*
|
|
145
|
+
* `roots` is the thing being drawn plus every frozen subtree. Those are not the same object
|
|
146
|
+
* when the engine's projection is collapsing the scene: the draw root is then the mirror, and
|
|
147
|
+
* validating only it reported three objects checked and zero divergences on a scene with two
|
|
148
|
+
* hundred frozen meshes, one of which really was stale. A freeze is authored on the authored
|
|
149
|
+
* scene, so the authored roots are checked whether or not they are what reaches the GPU.
|
|
150
|
+
*/
|
|
151
|
+
frame(...roots: readonly Object3D[]): void {
|
|
152
|
+
let checked = 0;
|
|
153
|
+
let gameOwned = 0;
|
|
154
|
+
const seen = new Set<Object3D>();
|
|
155
|
+
for (const root of roots) {
|
|
156
|
+
if (seen.has(root)) continue;
|
|
157
|
+
seen.add(root);
|
|
158
|
+
const result = validateWorldMatrices(root);
|
|
159
|
+
checked += result.checked;
|
|
160
|
+
gameOwned += result.gameOwned;
|
|
161
|
+
}
|
|
162
|
+
this.#checked = checked;
|
|
163
|
+
this.#gameOwned = gameOwned;
|
|
164
|
+
this.#frames += 1;
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
report(): IValidationReport {
|
|
168
|
+
return { checked: this.#checked, frames: this.#frames, gameOwned: this.#gameOwned };
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
/** The marker line for one reported window. */
|
|
173
|
+
export function formatValidationReport(report: IValidationReport): string {
|
|
174
|
+
return `${RENDERLIST_VALIDATE_MARKER}:${JSON.stringify({ ...report, divergences: 0 })}`;
|
|
175
|
+
}
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import { EquirectangularReflectionMapping, type Object3D } from "three";
|
|
2
|
+
|
|
3
|
+
/** Marker for an equirectangular environment below three's minimum PMREM cube size. */
|
|
4
|
+
export const ENVIRONMENT_TOO_SMALL_MARKER = "TN_ENVIRONMENT_TOO_SMALL";
|
|
5
|
+
/** Marker for a drawn material whose opacity three ignores. */
|
|
6
|
+
export const OPACITY_IGNORED_MARKER = "TN_OPACITY_IGNORED";
|
|
7
|
+
|
|
8
|
+
export interface IRenderTrapMaterial {
|
|
9
|
+
opacity?: number;
|
|
10
|
+
transparent?: boolean;
|
|
11
|
+
alphaHash?: boolean;
|
|
12
|
+
visible?: boolean;
|
|
13
|
+
name?: string;
|
|
14
|
+
type?: string;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
function opacityIgnored(
|
|
18
|
+
material: IRenderTrapMaterial | undefined,
|
|
19
|
+
): material is IRenderTrapMaterial {
|
|
20
|
+
return (
|
|
21
|
+
material != null &&
|
|
22
|
+
material.visible !== false &&
|
|
23
|
+
typeof material.opacity === "number" &&
|
|
24
|
+
material.opacity < 1 &&
|
|
25
|
+
material.transparent !== true &&
|
|
26
|
+
material.alphaHash !== true
|
|
27
|
+
);
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** Drawn materials whose opacity three ignores, each once. Structural reads only. */
|
|
31
|
+
export function opacityIgnoredMaterials(scene: Object3D): Set<IRenderTrapMaterial> {
|
|
32
|
+
const materials = new Set<IRenderTrapMaterial>();
|
|
33
|
+
scene.traverseVisible((object) => {
|
|
34
|
+
const drawable = object as Object3D & {
|
|
35
|
+
isMesh?: boolean;
|
|
36
|
+
isPoints?: boolean;
|
|
37
|
+
isLine?: boolean;
|
|
38
|
+
isSprite?: boolean;
|
|
39
|
+
material?: IRenderTrapMaterial | IRenderTrapMaterial[];
|
|
40
|
+
};
|
|
41
|
+
if (!(drawable.isMesh || drawable.isPoints || drawable.isLine || drawable.isSprite)) return;
|
|
42
|
+
const slot = drawable.material;
|
|
43
|
+
for (const material of Array.isArray(slot) ? slot : [slot])
|
|
44
|
+
if (opacityIgnored(material)) materials.add(material);
|
|
45
|
+
});
|
|
46
|
+
return materials;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** Up to five names for a marker line. */
|
|
50
|
+
export function materialExamples(materials: Iterable<IRenderTrapMaterial>): string[] {
|
|
51
|
+
return [...materials]
|
|
52
|
+
.slice(0, 5)
|
|
53
|
+
.map((material) => material.name || material.type || "unnamed material");
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** Structural reads only: Node materials, native adapters and test stubs share this audit. */
|
|
57
|
+
export function renderTrapAudit(scene: Object3D & { environment?: unknown }): string[] {
|
|
58
|
+
const lines: string[] = [];
|
|
59
|
+
const environment = scene.environment as
|
|
60
|
+
| { isTexture?: boolean; mapping?: number; image?: { width?: number } }
|
|
61
|
+
| null
|
|
62
|
+
| undefined;
|
|
63
|
+
const width = environment?.image?.width;
|
|
64
|
+
// three r185 derives PMREM's cube size from width / 4; LOD_MIN = 4 requires 16 px.
|
|
65
|
+
if (
|
|
66
|
+
environment?.isTexture === true &&
|
|
67
|
+
environment.mapping === EquirectangularReflectionMapping &&
|
|
68
|
+
typeof width === "number" &&
|
|
69
|
+
width / 4 < 16
|
|
70
|
+
) {
|
|
71
|
+
lines.push(
|
|
72
|
+
`${ENVIRONMENT_TOO_SMALL_MARKER}:${JSON.stringify({ width })} use an equirectangular environment at least 64 pixels wide for PMREM`,
|
|
73
|
+
);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
const materials = opacityIgnoredMaterials(scene);
|
|
77
|
+
const examples = materialExamples(materials);
|
|
78
|
+
if (materials.size > 0) {
|
|
79
|
+
lines.push(
|
|
80
|
+
`${OPACITY_IGNORED_MARKER}:${JSON.stringify({ materials: materials.size, examples })} set transparent: true or alphaHash: true on these materials so opacity takes effect`,
|
|
81
|
+
);
|
|
82
|
+
}
|
|
83
|
+
return lines;
|
|
84
|
+
}
|
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The engine telling the agent that built the scene what a human would otherwise find by playing.
|
|
3
|
+
*
|
|
4
|
+
* A scene reached 1,815 triangles per draw with its GPU ten times under budget and nobody knew,
|
|
5
|
+
* because the census and the phase split are measured every frame and nothing reads them. The
|
|
6
|
+
* frame already carries the shape: how many objects the cull considered, how many draws each pass
|
|
7
|
+
* submitted, how many casters are exempt, and what share of the frame the GPU actually used. This
|
|
8
|
+
* turns those numbers into a verdict, once per reported window.
|
|
9
|
+
*
|
|
10
|
+
* **The rule is derived, never a constant an author is told to revisit.** It fires when
|
|
11
|
+
*
|
|
12
|
+
* - the GPU used less than a third of the frame — the device is not the constraint, and
|
|
13
|
+
* - the JS render phase alone is longer than the display's own period — so the scene cannot make
|
|
14
|
+
* the display's rate even if everything else in the frame were free.
|
|
15
|
+
*
|
|
16
|
+
* Both numbers come from the frame meter. The display's period comes from the host's own
|
|
17
|
+
* presentation cap where there is one, and otherwise from the frame rate the game itself declared;
|
|
18
|
+
* no third source is invented, and a launch that can name neither gets no verdict rather than a
|
|
19
|
+
* guessed one.
|
|
20
|
+
*
|
|
21
|
+
* It is silent on an honestly GPU-bound scene with the same draw count, which is the property that
|
|
22
|
+
* makes it worth reading: a warning that fires on every heavy scene is a warning nobody reads.
|
|
23
|
+
*/
|
|
24
|
+
|
|
25
|
+
import type { IFrameBudgetWindow } from "../frame-budget.js";
|
|
26
|
+
import type { IRenderCameraCullReport } from "../render-camera-cull.js";
|
|
27
|
+
import type { FramePassKind } from "../render-pass-budget.js";
|
|
28
|
+
|
|
29
|
+
/** Marker printed at most once per reported window. */
|
|
30
|
+
export const SCENE_WARNING_MARKER = "TN_SCENE_WARNING";
|
|
31
|
+
|
|
32
|
+
/** The GPU share below which the device is not what the frame is waiting for. */
|
|
33
|
+
const GPU_IDLE_SHARE = 1 / 3;
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* What the frame already knows about the scene's shape.
|
|
37
|
+
*
|
|
38
|
+
* Every field is a count the engine measures anyway — the projection's cull census and the render
|
|
39
|
+
* pass budget — so the warning adds a reading, never a measurement.
|
|
40
|
+
*/
|
|
41
|
+
export interface ISceneShape {
|
|
42
|
+
/** Objects the projected-size cull looked at this window. */
|
|
43
|
+
readonly objectsConsidered: number;
|
|
44
|
+
/** Objects it hid. */
|
|
45
|
+
readonly culled: number;
|
|
46
|
+
/** Objects exempt from the gate because they cast shadows. */
|
|
47
|
+
readonly shadowExemptCasters: number;
|
|
48
|
+
/** Draws submitted per pass kind, from the render pass budget. */
|
|
49
|
+
readonly draws: Readonly<Partial<Record<FramePassKind, number>>>;
|
|
50
|
+
/** Triangles per draw across every pass; the number a merge or an atlas moves. */
|
|
51
|
+
readonly trianglesPerDraw: number;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** The verdict, and the shape behind it. */
|
|
55
|
+
export interface ISceneWarning {
|
|
56
|
+
readonly window: number;
|
|
57
|
+
/** The GPU's share of the frame, as a fraction. */
|
|
58
|
+
readonly gpuShare: number;
|
|
59
|
+
/** The JS render phase's mean, in milliseconds. */
|
|
60
|
+
readonly renderMs: number;
|
|
61
|
+
/** The period the display works at, in milliseconds, and where that number came from. */
|
|
62
|
+
readonly displayPeriodMs: number;
|
|
63
|
+
readonly displaySource: "host-cap" | "declared-target";
|
|
64
|
+
/** The largest thing the CPU describes every frame, and its share of the terms compared. */
|
|
65
|
+
readonly dominantTerm: string;
|
|
66
|
+
readonly dominantShare: number;
|
|
67
|
+
readonly shape: ISceneShape;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
function round(value: number): number {
|
|
71
|
+
return Math.round(value * 1000) / 1000;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* The display's own period, in milliseconds, or `undefined` when nothing can say.
|
|
76
|
+
*
|
|
77
|
+
* The host's presentation cap first, because on a native launch that is literally the rate frames
|
|
78
|
+
* reach the display at. A browser has no refresh-rate API, so the rate the game declared is the
|
|
79
|
+
* only honest second source — and it is the same number the resolution scaler already judges
|
|
80
|
+
* against, not a new one.
|
|
81
|
+
*/
|
|
82
|
+
export function displayPeriodMs(
|
|
83
|
+
declaredTargetFps: number | undefined,
|
|
84
|
+
): { ms: number; source: ISceneWarning["displaySource"] } | undefined {
|
|
85
|
+
const host = globalThis as { __tnPresentationCap?: unknown };
|
|
86
|
+
if (typeof host.__tnPresentationCap === "function") {
|
|
87
|
+
const capped: unknown = host.__tnPresentationCap();
|
|
88
|
+
if (typeof capped === "number" && Number.isFinite(capped) && capped > 0)
|
|
89
|
+
return { ms: 1_000 / capped, source: "host-cap" };
|
|
90
|
+
}
|
|
91
|
+
if (
|
|
92
|
+
declaredTargetFps !== undefined &&
|
|
93
|
+
Number.isFinite(declaredTargetFps) &&
|
|
94
|
+
declaredTargetFps > 0
|
|
95
|
+
)
|
|
96
|
+
return { ms: 1_000 / declaredTargetFps, source: "declared-target" };
|
|
97
|
+
return undefined;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* The verdict for one reported window, or `undefined` when the frame does not earn one.
|
|
102
|
+
*
|
|
103
|
+
* Fails closed in both directions: a window whose GPU was never measured gets no verdict, because
|
|
104
|
+
* "the GPU is idle" is a claim and an absent reading is not evidence for it; and a window with no
|
|
105
|
+
* shape to report gets none either, because a warning that cannot say what to change is noise.
|
|
106
|
+
*/
|
|
107
|
+
export function sceneWarning(
|
|
108
|
+
window: IFrameBudgetWindow,
|
|
109
|
+
shape: ISceneShape | undefined,
|
|
110
|
+
declaredTargetFps: number | undefined,
|
|
111
|
+
): ISceneWarning | undefined {
|
|
112
|
+
if (shape === undefined) return undefined;
|
|
113
|
+
const gpuMs = window.gpu?.mean;
|
|
114
|
+
const frameMs = window.presented.mean;
|
|
115
|
+
if (gpuMs === undefined || !(frameMs > 0)) return undefined;
|
|
116
|
+
const gpuShare = gpuMs / frameMs;
|
|
117
|
+
if (gpuShare >= GPU_IDLE_SHARE) return undefined;
|
|
118
|
+
const period = displayPeriodMs(declaredTargetFps);
|
|
119
|
+
if (period === undefined) return undefined;
|
|
120
|
+
const renderMs = window.phases.render.mean;
|
|
121
|
+
if (renderMs <= period.ms) return undefined;
|
|
122
|
+
|
|
123
|
+
// The terms are the things the CPU describes once per frame. They are counts, not milliseconds,
|
|
124
|
+
// and the record says so: the point is to name what to reduce, and the phase split beside it
|
|
125
|
+
// already says how much a reduction is worth.
|
|
126
|
+
const terms: readonly { term: string; count: number }[] = [
|
|
127
|
+
{ count: shape.objectsConsidered, term: "objectsConsidered" },
|
|
128
|
+
{ count: shape.draws.shadow ?? 0, term: "shadowDraws" },
|
|
129
|
+
{ count: shape.draws.main ?? 0, term: "mainDraws" },
|
|
130
|
+
{ count: shape.draws.reflection ?? 0, term: "reflectionDraws" },
|
|
131
|
+
];
|
|
132
|
+
let dominant = terms[0] ?? { count: 0, term: "objectsConsidered" };
|
|
133
|
+
let total = 0;
|
|
134
|
+
for (const candidate of terms) {
|
|
135
|
+
total += candidate.count;
|
|
136
|
+
if (candidate.count > dominant.count) dominant = candidate;
|
|
137
|
+
}
|
|
138
|
+
return {
|
|
139
|
+
displayPeriodMs: round(period.ms),
|
|
140
|
+
displaySource: period.source,
|
|
141
|
+
dominantShare: total > 0 ? round(dominant.count / total) : 0,
|
|
142
|
+
dominantTerm: dominant.term,
|
|
143
|
+
gpuShare: round(gpuShare),
|
|
144
|
+
renderMs: round(renderMs),
|
|
145
|
+
shape,
|
|
146
|
+
window: window.window,
|
|
147
|
+
};
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* The scene's shape for one window, from the counts the frame already reported.
|
|
152
|
+
*
|
|
153
|
+
* `undefined` when the window carries no pass split: without draws there is nothing to name, and
|
|
154
|
+
* a verdict built on an absent census would be a sentence about a scene nobody measured.
|
|
155
|
+
*/
|
|
156
|
+
export function describeSceneShape(
|
|
157
|
+
window: IFrameBudgetWindow,
|
|
158
|
+
cull: IRenderCameraCullReport | undefined,
|
|
159
|
+
): ISceneShape | undefined {
|
|
160
|
+
const passes = window.passes;
|
|
161
|
+
if (passes === undefined) return undefined;
|
|
162
|
+
const draws: Partial<Record<FramePassKind, number>> = {};
|
|
163
|
+
let totalDraws = 0;
|
|
164
|
+
let totalTriangles = 0;
|
|
165
|
+
for (const [kind, summary] of Object.entries(passes)) {
|
|
166
|
+
if (summary === undefined) continue;
|
|
167
|
+
draws[kind as FramePassKind] = Math.round(summary.draws.mean);
|
|
168
|
+
totalDraws += summary.draws.mean;
|
|
169
|
+
totalTriangles += summary.triangles.mean;
|
|
170
|
+
}
|
|
171
|
+
if (totalDraws <= 0) return undefined;
|
|
172
|
+
return {
|
|
173
|
+
culled: cull?.culled ?? 0,
|
|
174
|
+
draws,
|
|
175
|
+
objectsConsidered: cull?.considered ?? 0,
|
|
176
|
+
shadowExemptCasters: cull?.exemptShadowCasters ?? 0,
|
|
177
|
+
trianglesPerDraw: Math.round(totalTriangles / totalDraws),
|
|
178
|
+
};
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
/** The one-line summary a reader sees without opening a log viewer. */
|
|
182
|
+
export function describeSceneWarning(warning: ISceneWarning): string {
|
|
183
|
+
const gpuPercent = Math.round(warning.gpuShare * 100);
|
|
184
|
+
return `the GPU used ${gpuPercent}% of the frame while the render phase took ${warning.renderMs} ms against a ${warning.displayPeriodMs} ms display period; ${warning.dominantTerm} is the largest term at ${warning.shape.trianglesPerDraw} triangles per draw`;
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/** The marker line. */
|
|
188
|
+
export function formatSceneWarning(warning: ISceneWarning): string {
|
|
189
|
+
return `${SCENE_WARNING_MARKER}:${JSON.stringify(warning)}`;
|
|
190
|
+
}
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where the spans attach to three's own render path.
|
|
3
|
+
*
|
|
4
|
+
* Kept apart from the recorder because they are two different kinds of risk. The recorder is
|
|
5
|
+
* arithmetic over a stack and is proven by unit tests; this file reaches into another library's
|
|
6
|
+
* private methods, and every line of it is a bet about how three 0.185 is shaped. Reading them
|
|
7
|
+
* separately is how the bet stays visible.
|
|
8
|
+
*
|
|
9
|
+
* Every wrapper is an own property on the instance, so it is the object the frame actually uses
|
|
10
|
+
* and uninstalling restores the prototype's method. Three's private methods are read defensively:
|
|
11
|
+
* a renderer whose internals have moved loses that span rather than throwing, and the span simply
|
|
12
|
+
* does not appear in the report — an absent measurement, never a fabricated zero.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
import type { Object3D } from "three";
|
|
16
|
+
import { SPANS, type SpanId, beginSpan, endSpan, spanRecorder } from "./Spans.js";
|
|
17
|
+
|
|
18
|
+
/** The render call's span, by what three already calls the scene it was handed. */
|
|
19
|
+
function passSpan(scene: unknown, depth: number): SpanId {
|
|
20
|
+
if (depth === 0) return SPANS.mainPass;
|
|
21
|
+
let name = "";
|
|
22
|
+
if (
|
|
23
|
+
typeof scene === "object" &&
|
|
24
|
+
scene !== null &&
|
|
25
|
+
"name" in scene &&
|
|
26
|
+
typeof scene.name === "string"
|
|
27
|
+
) {
|
|
28
|
+
name = scene.name;
|
|
29
|
+
}
|
|
30
|
+
if (name.startsWith("Shadow Map")) return SPANS.shadowPass;
|
|
31
|
+
if (/reflect/iu.test(name)) return SPANS.reflectionPass;
|
|
32
|
+
return SPANS.nestedPass;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Gives the render list's `sort` a span, from the first list three hands over.
|
|
37
|
+
*
|
|
38
|
+
* The class is not exported, so the prototype is reached through an instance. Patching the prototype
|
|
39
|
+
* rather than the instance matters: three keeps one list per (scene, camera) pair, and an instance
|
|
40
|
+
* patch would miss every list the game had not drawn with yet.
|
|
41
|
+
*/
|
|
42
|
+
function patchRenderListSort(list: unknown, restore: (() => void)[]): void {
|
|
43
|
+
if (typeof list !== "object" || list === null) return;
|
|
44
|
+
const prototype: unknown = Object.getPrototypeOf(list);
|
|
45
|
+
if (
|
|
46
|
+
typeof prototype !== "object" ||
|
|
47
|
+
prototype === null ||
|
|
48
|
+
!("sort" in prototype) ||
|
|
49
|
+
typeof prototype.sort !== "function"
|
|
50
|
+
)
|
|
51
|
+
return;
|
|
52
|
+
const originalSort = prototype.sort;
|
|
53
|
+
prototype.sort = function spanSort(this: unknown, ...sortArgs: unknown[]): unknown {
|
|
54
|
+
beginSpan(SPANS.sort);
|
|
55
|
+
try {
|
|
56
|
+
return originalSort.apply(this, sortArgs);
|
|
57
|
+
} finally {
|
|
58
|
+
endSpan(SPANS.sort);
|
|
59
|
+
}
|
|
60
|
+
};
|
|
61
|
+
restore.push(() => {
|
|
62
|
+
prototype.sort = originalSort;
|
|
63
|
+
});
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** The slice of the raw three renderer the probes wrap. Structural, so a test can stand in a fake. */
|
|
67
|
+
export interface ISpanProbeTarget {
|
|
68
|
+
render(scene: unknown, camera: unknown): unknown;
|
|
69
|
+
_projectObject?(...args: unknown[]): void;
|
|
70
|
+
_renderObjectDirect?(...args: unknown[]): void;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Wraps the renderer's own render path so each part of a frame lands in its own span.
|
|
75
|
+
*
|
|
76
|
+
* Every wrapper is an own property on the instance, so it is the object the frame actually uses and
|
|
77
|
+
* uninstalling restores the prototype's method. Three's private methods are read defensively: a
|
|
78
|
+
* renderer whose internals have moved loses that span rather than throwing, and the span simply
|
|
79
|
+
* does not appear in the report — an absent measurement, never a fabricated zero.
|
|
80
|
+
*
|
|
81
|
+
* The recursion guards matter: `_projectObject` calls itself once per child, so only the outermost
|
|
82
|
+
* call opens a span, and `render` is deliberately not guarded because a nested render *is* the
|
|
83
|
+
* shadow and reflection passes.
|
|
84
|
+
*/
|
|
85
|
+
export function installSpanProbes(target: ISpanProbeTarget, root: Object3D): () => void {
|
|
86
|
+
const restore: (() => void)[] = [];
|
|
87
|
+
const previousRender = target.render;
|
|
88
|
+
let renderDepth = 0;
|
|
89
|
+
target.render = function spanRender(this: unknown, scene: unknown, camera: unknown): unknown {
|
|
90
|
+
const id = passSpan(scene, renderDepth);
|
|
91
|
+
renderDepth += 1;
|
|
92
|
+
beginSpan(id);
|
|
93
|
+
try {
|
|
94
|
+
return previousRender.call(this, scene, camera);
|
|
95
|
+
} finally {
|
|
96
|
+
renderDepth -= 1;
|
|
97
|
+
endSpan(id);
|
|
98
|
+
}
|
|
99
|
+
};
|
|
100
|
+
restore.push(() => {
|
|
101
|
+
target.render = previousRender;
|
|
102
|
+
});
|
|
103
|
+
|
|
104
|
+
const projectObject = target._projectObject;
|
|
105
|
+
if (typeof projectObject === "function") {
|
|
106
|
+
let projectDepth = 0;
|
|
107
|
+
let listPatched = false;
|
|
108
|
+
target._projectObject = function spanProjectObject(this: unknown, ...args: unknown[]): void {
|
|
109
|
+
if (!listPatched) {
|
|
110
|
+
listPatched = true;
|
|
111
|
+
patchRenderListSort(args[3], restore);
|
|
112
|
+
}
|
|
113
|
+
if (projectDepth > 0) {
|
|
114
|
+
projectObject.apply(this, args);
|
|
115
|
+
return;
|
|
116
|
+
}
|
|
117
|
+
projectDepth += 1;
|
|
118
|
+
beginSpan(SPANS.projectObject);
|
|
119
|
+
try {
|
|
120
|
+
projectObject.apply(this, args);
|
|
121
|
+
} finally {
|
|
122
|
+
projectDepth -= 1;
|
|
123
|
+
endSpan(SPANS.projectObject);
|
|
124
|
+
}
|
|
125
|
+
};
|
|
126
|
+
restore.push(() => {
|
|
127
|
+
target._projectObject = projectObject;
|
|
128
|
+
});
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
const renderObjectDirect = target._renderObjectDirect;
|
|
132
|
+
if (typeof renderObjectDirect === "function") {
|
|
133
|
+
target._renderObjectDirect = function spanRenderObjectDirect(
|
|
134
|
+
this: unknown,
|
|
135
|
+
...args: unknown[]
|
|
136
|
+
): void {
|
|
137
|
+
beginSpan(SPANS.draw);
|
|
138
|
+
try {
|
|
139
|
+
renderObjectDirect.apply(this, args);
|
|
140
|
+
} finally {
|
|
141
|
+
endSpan(SPANS.draw);
|
|
142
|
+
}
|
|
143
|
+
};
|
|
144
|
+
restore.push(() => {
|
|
145
|
+
target._renderObjectDirect = renderObjectDirect;
|
|
146
|
+
});
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
// The walk is patched on the scene's own prototype, not on the root object, because the render
|
|
150
|
+
// phase walks more than one scene: the game's, the projection's mirror, and each shadow and
|
|
151
|
+
// reflection pass's. All of them are Scenes, and a per-object patch would open a span per child
|
|
152
|
+
// of a walk that recurses through every node.
|
|
153
|
+
const scenePrototype: unknown = Object.getPrototypeOf(root);
|
|
154
|
+
if (
|
|
155
|
+
typeof scenePrototype === "object" &&
|
|
156
|
+
scenePrototype !== null &&
|
|
157
|
+
"updateMatrixWorld" in scenePrototype &&
|
|
158
|
+
typeof scenePrototype.updateMatrixWorld === "function"
|
|
159
|
+
) {
|
|
160
|
+
const sceneUpdate = scenePrototype.updateMatrixWorld;
|
|
161
|
+
let walkDepth = 0;
|
|
162
|
+
scenePrototype.updateMatrixWorld = function spanUpdateMatrixWorld(
|
|
163
|
+
this: Object3D,
|
|
164
|
+
force?: boolean,
|
|
165
|
+
): void {
|
|
166
|
+
const active = spanRecorder();
|
|
167
|
+
// Only the outermost walk, and only inside the render phase: a walk run from a game's own
|
|
168
|
+
// update tick is not render-phase work, and attributing it here would silently inflate the
|
|
169
|
+
// phase the spans exist to explain.
|
|
170
|
+
if (walkDepth > 0 || active === undefined || active.depth === 0) {
|
|
171
|
+
sceneUpdate.call(this, force);
|
|
172
|
+
return;
|
|
173
|
+
}
|
|
174
|
+
walkDepth += 1;
|
|
175
|
+
beginSpan(SPANS.sceneUpdate);
|
|
176
|
+
try {
|
|
177
|
+
sceneUpdate.call(this, force);
|
|
178
|
+
} finally {
|
|
179
|
+
walkDepth -= 1;
|
|
180
|
+
endSpan(SPANS.sceneUpdate);
|
|
181
|
+
}
|
|
182
|
+
};
|
|
183
|
+
restore.push(() => {
|
|
184
|
+
scenePrototype.updateMatrixWorld = sceneUpdate;
|
|
185
|
+
});
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
return () => {
|
|
189
|
+
for (let index = restore.length - 1; index >= 0; index -= 1) restore[index]?.();
|
|
190
|
+
};
|
|
191
|
+
}
|