@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,518 @@
|
|
|
1
|
+
import type { IAssetSlot, IGpuPlacement, IRegion, IValidationSnapshot } from "./world-gpu-types.js";
|
|
2
|
+
import { DRAW_ARGS_WORDS, LOCAL_WORDS } from "./world-gpu-types.js";
|
|
3
|
+
|
|
4
|
+
// Defined with the layout constants they belong to, and re-exported here because they are the width
|
|
5
|
+
// of every record this module reads. Keeping them in one place is what leaves the two modules a
|
|
6
|
+
// chain of one direction: the validation reads the types, and the types read nothing here.
|
|
7
|
+
export { DRAW_ARGS_WORDS, LOCAL_WORDS };
|
|
8
|
+
|
|
9
|
+
/** Keys a mismatch line names before the rest are counted and not printed. */
|
|
10
|
+
export const VALIDATE_REPORTED_KEYS = 10;
|
|
11
|
+
|
|
12
|
+
/** Keys a matrix or indirect-record line names, which carry more numbers than a count line does. */
|
|
13
|
+
export const MATRIX_REPORTED_KEYS = 5;
|
|
14
|
+
|
|
15
|
+
/** Meshes a `mesh=` line names, on the same budget as the record lines above. */
|
|
16
|
+
export const MESH_REPORTED_MESHES = 5;
|
|
17
|
+
|
|
18
|
+
/** Two matrices within this of each other are the same one written through a `mat4` product. */
|
|
19
|
+
export const MATRIX_TOLERANCE = 1e-3;
|
|
20
|
+
|
|
21
|
+
/** Characters of a cause a `cause=` line carries, so one message cannot own the report. */
|
|
22
|
+
export const CAUSE_CHARS = 160;
|
|
23
|
+
|
|
24
|
+
/** The one matrix `liveKeyInstances` composes into, reused per placement as the kernel's own is. */
|
|
25
|
+
export const LIVE_MATRIX = new Float32Array(LOCAL_WORDS);
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Whether two gate tables are the same one, so a level key minted after the table was written
|
|
29
|
+
* rewrites it and a swap that arrives with nothing new does not. A level the world has not minted a
|
|
30
|
+
* key for carries `parts: 0`, which is what the kernel's own loop then draws for it: nothing.
|
|
31
|
+
*/
|
|
32
|
+
export function sameGates(one: IAssetSlot, other: IAssetSlot): boolean {
|
|
33
|
+
if (one.cull !== other.cull) return false;
|
|
34
|
+
if ((one.shadowFallback === false) !== (other.shadowFallback === false)) return false;
|
|
35
|
+
if ((one.impostor === true) !== (other.impostor === true)) return false;
|
|
36
|
+
if (one.distances.length !== other.distances.length) return false;
|
|
37
|
+
for (const [index, distance] of one.distances.entries())
|
|
38
|
+
if (distance !== other.distances[index]) return false;
|
|
39
|
+
if (one.levels.length !== other.levels.length) return false;
|
|
40
|
+
for (const [index, level] of one.levels.entries()) {
|
|
41
|
+
const gate = other.levels[index];
|
|
42
|
+
if (gate === undefined || gate.firstKey !== level.firstKey || gate.parts !== level.parts)
|
|
43
|
+
return false;
|
|
44
|
+
}
|
|
45
|
+
return true;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** One word of an indirect readback, out of range being the zero a record that was never written holds. */
|
|
49
|
+
export function word(readback: Uint32Array, at: number): number {
|
|
50
|
+
return (readback[at] ?? 0) as number;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** The translation of the `mat4` at slot `at`, which is what a draw places and a line can name. */
|
|
54
|
+
export function xyz(matrices: Float32Array, at: number): string {
|
|
55
|
+
const matrix = at * LOCAL_WORDS;
|
|
56
|
+
if (matrix + LOCAL_WORDS > matrices.length) return "[]";
|
|
57
|
+
return (
|
|
58
|
+
`[${(matrices[matrix + 12] as number).toFixed(3)},` +
|
|
59
|
+
`${(matrices[matrix + 13] as number).toFixed(3)},` +
|
|
60
|
+
`${(matrices[matrix + 14] as number).toFixed(3)}]`
|
|
61
|
+
);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* Whether two runs of `mat4` hold the same matrices, as a set and not as a sequence.
|
|
66
|
+
*
|
|
67
|
+
* The kernel appends through an atomic, so the order two dispatches fill a region's run in is the
|
|
68
|
+
* order the device scheduled them in and is not the order the reference walked the placements. The
|
|
69
|
+
* counts agree over a set that agrees; a set that does not is a run one slot out, a matrix that was
|
|
70
|
+
* never written, or a `firstInstance` the draw reads from a different place — none of which a count
|
|
71
|
+
* can see. Sorted by translation, because that is what orders a placement, and compared with a
|
|
72
|
+
* tolerance, because a matrix written through a product of two floats is not bit-equal to either.
|
|
73
|
+
*/
|
|
74
|
+
export function sameMatrices(
|
|
75
|
+
gpu: Float32Array,
|
|
76
|
+
gpuStart: number,
|
|
77
|
+
gpuCount: number,
|
|
78
|
+
cpu: Float32Array,
|
|
79
|
+
cpuStart: number,
|
|
80
|
+
cpuCount: number,
|
|
81
|
+
tolerance: number,
|
|
82
|
+
): boolean {
|
|
83
|
+
const one = sorted(gpu, gpuStart, gpuCount);
|
|
84
|
+
const other = sorted(cpu, cpuStart, cpuCount);
|
|
85
|
+
if (one.length !== other.length) return false;
|
|
86
|
+
for (const [index, matrix] of one.entries()) {
|
|
87
|
+
const against = other[index] as Float32Array;
|
|
88
|
+
for (let word = 0; word < LOCAL_WORDS; word += 1)
|
|
89
|
+
if (Math.abs((matrix[word] as number) - (against[word] as number)) > tolerance) return false;
|
|
90
|
+
}
|
|
91
|
+
return true;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* Whether two part offsets are the same matrix word for word. A re-dress copies the part's `Matrix4`
|
|
96
|
+
* into a fresh array, so a re-registration of the same key is the same `local` by value and not by
|
|
97
|
+
* reference; comparing the bytes is what makes it a no-op.
|
|
98
|
+
*/
|
|
99
|
+
export function sameLocal(one: Float32Array, other: Float32Array): boolean {
|
|
100
|
+
if (one.length !== other.length) return false;
|
|
101
|
+
for (let word = 0; word < one.length; word += 1)
|
|
102
|
+
if ((one[word] as number) !== (other[word] as number)) return false;
|
|
103
|
+
return true;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/** One run of `mat4` as views, ordered by translation, and short reads truncated rather than read past. */
|
|
107
|
+
export function sorted(matrices: Float32Array, start: number, count: number): Float32Array[] {
|
|
108
|
+
const out: Float32Array[] = [];
|
|
109
|
+
for (let taken = 0; taken < count; taken += 1) {
|
|
110
|
+
const at = (start + taken) * LOCAL_WORDS;
|
|
111
|
+
if (at < 0 || at + LOCAL_WORDS > matrices.length) break;
|
|
112
|
+
out.push(matrices.subarray(at, at + LOCAL_WORDS));
|
|
113
|
+
}
|
|
114
|
+
out.sort(
|
|
115
|
+
(one, other) =>
|
|
116
|
+
(one[12] as number) - (other[12] as number) || (one[14] as number) - (other[14] as number),
|
|
117
|
+
);
|
|
118
|
+
return out;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/** `out * into` at `at`, column-major, which is the element order both matrices are written in. */ export function compose(
|
|
122
|
+
out: Float32Array,
|
|
123
|
+
into: Float32Array,
|
|
124
|
+
target: Float32Array,
|
|
125
|
+
at: number,
|
|
126
|
+
): void {
|
|
127
|
+
for (let column = 0; column < 4; column += 1)
|
|
128
|
+
for (let row = 0; row < 4; row += 1) {
|
|
129
|
+
let sum = 0;
|
|
130
|
+
for (let k = 0; k < 4; k += 1)
|
|
131
|
+
sum += (out[k * 4 + row] as number) * (into[column * 4 + k] as number);
|
|
132
|
+
target[at + column * 4 + row] = sum;
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* One dressed main mesh's draw, as the owner's own live state says it, and nothing from this file's
|
|
138
|
+
* tables.
|
|
139
|
+
*
|
|
140
|
+
* This is the check that cannot be wrong in the same way the kernel is. {@link cullAndSelect}
|
|
141
|
+
* addresses a level's parts as `levels[gate.x + level].y + part`, and the gate table holds the
|
|
142
|
+
* `firstKey` the scene itself reported through `levelKeys`, so a key/record/mesh mapping that is
|
|
143
|
+
* wrong is reproduced on both sides of the comparison and reads as agreement: a real WebGPU walk
|
|
144
|
+
* printed `ok` over a forest it was drawing with another tree's geometry. The three numbers here
|
|
145
|
+
* come from the other side of the seam — the mesh's own `geometry.indirect` record, the mesh's own
|
|
146
|
+
* name, and the instances the owner's own gates and the camera's own planes select for that name —
|
|
147
|
+
* so the one question they can answer is the one that matters: does the record this mesh draws from
|
|
148
|
+
* hold exactly the instances that mesh's key is owed.
|
|
149
|
+
*/
|
|
150
|
+
export interface IMeshDraw {
|
|
151
|
+
/** The dressed mesh's own name, which is the main key: `asset:level:part`. */
|
|
152
|
+
readonly name: string;
|
|
153
|
+
/** `geometry.indirectOffset / DRAW_ARGS_BYTES` — the record the draw reads, not one the tables name. */
|
|
154
|
+
readonly record: number;
|
|
155
|
+
/**
|
|
156
|
+
* Every instance the owner's live gates and the camera's planes select for this key, `mat4` after
|
|
157
|
+
* `mat4`: the whole answer, and never the per-cell records this path's own refilter left behind.
|
|
158
|
+
*/
|
|
159
|
+
readonly instances: Float32Array;
|
|
160
|
+
/**
|
|
161
|
+
* Whether the mesh's own geometry reads the args buffer the readback came from, at the record above:
|
|
162
|
+
* `geometry.indirect === scene.args` and `geometry.indirectOffset === region.argsIndex *
|
|
163
|
+
* DRAW_ARGS_BYTES`, answered by the owner from the actual mesh. A record offset can agree with the
|
|
164
|
+
* live buffer while the mesh still points at an older buffer with the same numeric offset — the
|
|
165
|
+
* args buffer is allocated independently of `drawn`, and a mint can replace it under a dressed mesh
|
|
166
|
+
* — so an offset check alone reads `ok` over a mesh drawing a buffer nothing writes. A missing value
|
|
167
|
+
* is not a pass: only `true` is bound.
|
|
168
|
+
*/
|
|
169
|
+
readonly bound?: boolean;
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
/** What the independent per-mesh check found, in the shape the report folds in. */
|
|
173
|
+
export interface IMeshDrawComparison {
|
|
174
|
+
/** Meshes whose own record was read back and held against the live-state instances. */
|
|
175
|
+
readonly compared: number;
|
|
176
|
+
readonly mismatched: number;
|
|
177
|
+
readonly mismatches: readonly string[];
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* Every dressed main mesh's own record, against the instances its own key is owed, as a set rather
|
|
182
|
+
* than a sequence — the kernel appends through an atomic, so a device's order is not the CPU's.
|
|
183
|
+
*
|
|
184
|
+
* Equality, and not containment, because the reference is now the whole answer: the owner's gates
|
|
185
|
+
* and the camera's planes over the scene's own placements, which is everything the dispatch reads.
|
|
186
|
+
* Containment was the right relation when the other side was the CPU path's per-cell records, which
|
|
187
|
+
* are the records a refilter left and go stale the moment the GPU scene bypasses it — a reference
|
|
188
|
+
* that can be a superset cannot name a level selected at the wrong distance, and a far tree drawn
|
|
189
|
+
* at its near level is what that looks like in the picture.
|
|
190
|
+
*/
|
|
191
|
+
export function compareMeshDraws(
|
|
192
|
+
gpu: Uint32Array,
|
|
193
|
+
drawn: Float32Array,
|
|
194
|
+
draws: readonly IMeshDraw[],
|
|
195
|
+
regions: readonly IRegion[],
|
|
196
|
+
): IMeshDrawComparison {
|
|
197
|
+
const mismatches: string[] = [];
|
|
198
|
+
let mismatched = 0;
|
|
199
|
+
for (const draw of draws) {
|
|
200
|
+
const record = draw.record * DRAW_ARGS_WORDS;
|
|
201
|
+
const landed = word(gpu, record + 1);
|
|
202
|
+
const first = word(gpu, record + 4);
|
|
203
|
+
// A stale binding is a mismatch the counts and matrices cannot see: the mesh's own geometry
|
|
204
|
+
// points at an args buffer the readback did not come from, so whatever this record holds is not
|
|
205
|
+
// what that mesh draws. Only an explicit `true` is bound, so a caller that forgets the field
|
|
206
|
+
// fails closed rather than reading as agreement.
|
|
207
|
+
if (draw.bound !== true) {
|
|
208
|
+
mismatched += 1;
|
|
209
|
+
if (mismatches.length >= MESH_REPORTED_MESHES) continue;
|
|
210
|
+
const owner = regions.find((region) => region.argsIndex === draw.record);
|
|
211
|
+
mismatches.push(
|
|
212
|
+
`mesh=${draw.name} record=${String(draw.record)} ` +
|
|
213
|
+
`region=${owner?.name ?? "none"} indirect=stale count gpu=${String(landed)} ` +
|
|
214
|
+
`live=${String(draw.instances.length / LOCAL_WORDS)}`,
|
|
215
|
+
);
|
|
216
|
+
continue;
|
|
217
|
+
}
|
|
218
|
+
if (
|
|
219
|
+
sameMatrices(
|
|
220
|
+
drawn,
|
|
221
|
+
first,
|
|
222
|
+
landed,
|
|
223
|
+
draw.instances,
|
|
224
|
+
0,
|
|
225
|
+
draw.instances.length / LOCAL_WORDS,
|
|
226
|
+
MATRIX_TOLERANCE,
|
|
227
|
+
)
|
|
228
|
+
)
|
|
229
|
+
continue;
|
|
230
|
+
mismatched += 1;
|
|
231
|
+
if (mismatches.length >= MESH_REPORTED_MESHES) continue;
|
|
232
|
+
// The region that owns the record the mesh read, which is the name that says whether the mesh
|
|
233
|
+
// and the scene ever agreed on which record this key is.
|
|
234
|
+
const owner = regions.find((region) => region.argsIndex === draw.record);
|
|
235
|
+
mismatches.push(
|
|
236
|
+
`mesh=${draw.name} record=${String(draw.record)} ` +
|
|
237
|
+
`region=${owner?.name ?? "none"} count gpu=${String(landed)} ` +
|
|
238
|
+
`live=${String(draw.instances.length / LOCAL_WORDS)} ` +
|
|
239
|
+
`firstMatrix gpu=${xyz(drawn, first)} live=${xyz(draw.instances, 0)}`,
|
|
240
|
+
);
|
|
241
|
+
}
|
|
242
|
+
return { compared: draws.length, mismatched, mismatches };
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/** What one landed readback concluded, in the three words a log line can carry. */
|
|
246
|
+
export type GpuSceneVerdict = "ok" | "mismatch" | "error";
|
|
247
|
+
|
|
248
|
+
/** One landed readback's verdict, its one line, and the detail lines under it. */
|
|
249
|
+
export interface IGpuSceneValidation {
|
|
250
|
+
readonly verdict: GpuSceneVerdict;
|
|
251
|
+
readonly line: string;
|
|
252
|
+
readonly lines: readonly string[];
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
/**
|
|
256
|
+
* The memory numbers a validation line can carry, all of them optional.
|
|
257
|
+
*
|
|
258
|
+
* The first seven are three's `info.memory` fields (`WebGPURenderer`, 0.185); a backend that tracks
|
|
259
|
+
* none of them reports none, which is why every field is optional and only finite numbers are
|
|
260
|
+
* printed — an absent reading is not a zero. `footprintBytes` is the sum of this scene's own storage
|
|
261
|
+
* buffer `footprint()` bytes, the one number here Three did not write.
|
|
262
|
+
*/
|
|
263
|
+
export type GpuSceneMemoryField =
|
|
264
|
+
| "storageAttributes"
|
|
265
|
+
| "storageAttributesSize"
|
|
266
|
+
| "indirectStorageAttributes"
|
|
267
|
+
| "indirectStorageAttributesSize"
|
|
268
|
+
| "readbackBuffers"
|
|
269
|
+
| "readbackBuffersSize"
|
|
270
|
+
| "total"
|
|
271
|
+
| "footprintBytes";
|
|
272
|
+
|
|
273
|
+
/** One validation's memory reading; a field is absent when the backend did not offer a finite one. */
|
|
274
|
+
export type GpuSceneMemory = Partial<Record<GpuSceneMemoryField, number>>;
|
|
275
|
+
|
|
276
|
+
export const MEMORY_FIELDS = [
|
|
277
|
+
"storageAttributes",
|
|
278
|
+
"storageAttributesSize",
|
|
279
|
+
"indirectStorageAttributes",
|
|
280
|
+
"indirectStorageAttributesSize",
|
|
281
|
+
"readbackBuffers",
|
|
282
|
+
"readbackBuffersSize",
|
|
283
|
+
"total",
|
|
284
|
+
"footprintBytes",
|
|
285
|
+
] as const satisfies readonly GpuSceneMemoryField[];
|
|
286
|
+
|
|
287
|
+
/**
|
|
288
|
+
* The one placement nearest the camera (in XZ) a zero/zero comparison was handed, as the dispatch's
|
|
289
|
+
* own snapshot held it. Every number is the snapshot's, never the live scene's: the camera's eye and
|
|
290
|
+
* this placement's sphere, root translation, slot, slot cull, horizontal distance and the margin to
|
|
291
|
+
* the nearest of the six frustum planes are what say whether the snapshot held no live source or
|
|
292
|
+
* held one the camera, sphere, range or frustum rejected. A field is omitted, not printed as a fake
|
|
293
|
+
* zero, when the snapshot has no finite number for it.
|
|
294
|
+
*/
|
|
295
|
+
export interface IValidationNearest {
|
|
296
|
+
/** The bounding sphere: X, Y, Z and the radius. */
|
|
297
|
+
readonly centre: readonly [number, number, number];
|
|
298
|
+
readonly radius: number;
|
|
299
|
+
/** The placement matrix's translation, which is what a draw places. */
|
|
300
|
+
readonly root: readonly [number, number, number];
|
|
301
|
+
/** The asset slot the placement names. */
|
|
302
|
+
readonly slot: number;
|
|
303
|
+
/** The slot's authored cull distance, or absent when it has none. */
|
|
304
|
+
readonly cull?: number;
|
|
305
|
+
/** `hypot(cx - eye.x, cz - eye.z)`, the distance the level and cull gates read. */
|
|
306
|
+
readonly distance: number;
|
|
307
|
+
/** The least `plane·centre + plane.constant + radius` over the six planes: negative is rejected. */
|
|
308
|
+
readonly margin: number;
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
/**
|
|
312
|
+
* Why a comparison that landed both counts at zero was handed nothing: the snapshot's own camera eye,
|
|
313
|
+
* how many placements it held and how many of them were live, and the one live placement nearest the
|
|
314
|
+
* camera in XZ. Taken from the snapshot, so nothing that streams while the bytes are in flight can
|
|
315
|
+
* rewrite the answer. Attached only when `instancesGpu` and `instancesCpu` are both zero.
|
|
316
|
+
*/
|
|
317
|
+
export interface IValidationProbe {
|
|
318
|
+
readonly eye: readonly [number, number, number];
|
|
319
|
+
/** Placements the snapshot held, live and released. */
|
|
320
|
+
readonly snapshot: number;
|
|
321
|
+
/** Placements whose slot was not `SLOT_NONE`, the only ones the kernel considers. */
|
|
322
|
+
readonly live: number;
|
|
323
|
+
/** Absent when the snapshot held no live placement to name. */
|
|
324
|
+
readonly nearest?: IValidationNearest;
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
/** What a landed readback is judged on, gathered from the scene before it is formatted. */
|
|
328
|
+
export interface IGpuSceneComparison {
|
|
329
|
+
/** Keys whose GPU instance count was read back and held against the reference. */
|
|
330
|
+
readonly compared: number;
|
|
331
|
+
readonly instancesGpu: number;
|
|
332
|
+
readonly instancesCpu: number;
|
|
333
|
+
/** Up to {@link VALIDATE_REPORTED_KEYS} `name gpu=… cpu=…` lines; the count is the whole total. */
|
|
334
|
+
readonly mismatches: readonly string[];
|
|
335
|
+
readonly mismatched: number;
|
|
336
|
+
/**
|
|
337
|
+
* Keys whose drawn matrices, `firstInstance` or `indexCount` disagreed, and up to
|
|
338
|
+
* {@link MATRIX_REPORTED_KEYS} of them by name. The counts above are what the dispatch promised;
|
|
339
|
+
* these are what the draw reads, which is a different question and the one the picture answers.
|
|
340
|
+
*/
|
|
341
|
+
readonly matricesMismatched: number;
|
|
342
|
+
readonly matrixMismatches: readonly string[];
|
|
343
|
+
/**
|
|
344
|
+
* Dressed main meshes whose own record was read back and held against the CPU path's own records
|
|
345
|
+
* for that mesh's key, and up to {@link MESH_REPORTED_MESHES} of them by name. This is the check
|
|
346
|
+
* the reference above cannot make: a key/record/mesh mapping that is wrong is one both sides
|
|
347
|
+
* reproduce, and a mesh drawing another asset's placements out of its own record is the picture
|
|
348
|
+
* that proves it.
|
|
349
|
+
*/
|
|
350
|
+
readonly meshMismatched: number;
|
|
351
|
+
readonly meshMismatches: readonly string[];
|
|
352
|
+
/** Resident placements the scene held when the readback was issued. */
|
|
353
|
+
readonly placed: number;
|
|
354
|
+
/** The device's last uncaptured error, or `""` for none since the last check reported one. */
|
|
355
|
+
readonly deviceError: string;
|
|
356
|
+
/** What stopped the check — a rejected readback, say. Non-empty is an `error` on its own. */
|
|
357
|
+
readonly cause?: string;
|
|
358
|
+
/**
|
|
359
|
+
* What the device and this scene held when the check reported. Absent when neither offered a
|
|
360
|
+
* finite number, and a field is omitted rather than printed as zero when its backend has none.
|
|
361
|
+
*/
|
|
362
|
+
readonly memory?: GpuSceneMemory;
|
|
363
|
+
/** The snapshot's own camera and nearest live placement, when both instance totals landed zero. */
|
|
364
|
+
readonly probe?: IValidationProbe;
|
|
365
|
+
}
|
|
366
|
+
|
|
367
|
+
/**
|
|
368
|
+
* The verdict and the lines one landed readback reports, as `TN_WORLD_GPU_SCENE_VALIDATE`.
|
|
369
|
+
*
|
|
370
|
+
* `ok` is a claim that the GPU drew what the reference draws, so it takes three things: every key's
|
|
371
|
+
* count landing equal, every key's record and matrices landing where the reference put them, and
|
|
372
|
+
* something to land. A dispatch the device refused leaves the args buffer holding what the clear
|
|
373
|
+
* pass wrote, which compares equal to a scene with nothing in it — a real WebGPU run printed
|
|
374
|
+
* `ok keys=0` 956 times while the cull pipeline was being refused for a binding 48 bytes short, which
|
|
375
|
+
* is a check that reports success precisely when the kernel does nothing. So comparing nothing while
|
|
376
|
+
* placements exist is an `error`, and a device that raised anything uncaptured is an `error`
|
|
377
|
+
* whatever the counts say, because every count in a buffer the device has already invalidated is not
|
|
378
|
+
* evidence of anything.
|
|
379
|
+
*
|
|
380
|
+
* The three mismatch families are counted apart and all are a `mismatch`: a key that drew the right
|
|
381
|
+
* number of instances at the wrong place or through a record naming no triangle is the failure a
|
|
382
|
+
* count cannot see, and a walk that printed `mismatched=0` over a forest it never drew is what that
|
|
383
|
+
* reads like. The third is the one the two above cannot find at all: every key the reference names
|
|
384
|
+
* and every record it reads is named by this same file, so a key/record/mesh mapping that is wrong is
|
|
385
|
+
* one they both reproduce, and the dressed mesh's own record, against the CPU path's own records,
|
|
386
|
+
* is the only pair of numbers here that were not written by the same hand.
|
|
387
|
+
*
|
|
388
|
+
* An `error` always names its cause on one `cause=` line: the checks that fail here fail silently
|
|
389
|
+
* otherwise, and a line reading `error` with nothing after it is the report that hid a refused
|
|
390
|
+
* pipeline in the first place.
|
|
391
|
+
*/
|
|
392
|
+
/** One `[x,y,z]` at three decimals, the precision `xyz` names a matrix translation with. */
|
|
393
|
+
export function triple(values: readonly [number, number, number]): string {
|
|
394
|
+
return (
|
|
395
|
+
`[${(values[0] as number).toFixed(3)},` +
|
|
396
|
+
`${(values[1] as number).toFixed(3)},${(values[2] as number).toFixed(3)}]`
|
|
397
|
+
);
|
|
398
|
+
}
|
|
399
|
+
|
|
400
|
+
/** The `key=value` fields a zero/zero comparison's probe adds after the memory fields. */
|
|
401
|
+
export function probeFields(probe: IValidationProbe): string[] {
|
|
402
|
+
const out = [
|
|
403
|
+
`eye=${triple(probe.eye)}`,
|
|
404
|
+
`snapshot=${String(probe.snapshot)}`,
|
|
405
|
+
`live=${String(probe.live)}`,
|
|
406
|
+
];
|
|
407
|
+
const near = probe.nearest;
|
|
408
|
+
if (near === undefined) return out;
|
|
409
|
+
out.push(
|
|
410
|
+
`nearSphere=${triple(near.centre)}`,
|
|
411
|
+
`nearRadius=${near.radius.toFixed(3)}`,
|
|
412
|
+
`nearRoot=${triple(near.root)}`,
|
|
413
|
+
`nearSlot=${String(near.slot)}`,
|
|
414
|
+
);
|
|
415
|
+
if (near.cull !== undefined) out.push(`nearCull=${near.cull.toFixed(3)}`);
|
|
416
|
+
out.push(`nearXZ=${near.distance.toFixed(3)}`, `nearMargin=${near.margin.toFixed(3)}`);
|
|
417
|
+
return out;
|
|
418
|
+
}
|
|
419
|
+
|
|
420
|
+
/**
|
|
421
|
+
* The snapshot's own camera and nearest live placement, for a comparison both of whose counts landed
|
|
422
|
+
* zero. The scan only picks the nearest; the six-plane margin is computed for that one placement
|
|
423
|
+
* alone, not for every placement the reference walked, and a field the snapshot has no finite number
|
|
424
|
+
* for is omitted rather than printed as a fake zero.
|
|
425
|
+
*/
|
|
426
|
+
export function zeroComparisonProbe(snapshot: IValidationSnapshot): IValidationProbe {
|
|
427
|
+
const eye: readonly [number, number, number] = [
|
|
428
|
+
snapshot.camera.x,
|
|
429
|
+
snapshot.camera.y,
|
|
430
|
+
snapshot.camera.z,
|
|
431
|
+
];
|
|
432
|
+
let live = 0;
|
|
433
|
+
let nearest: IGpuPlacement | undefined;
|
|
434
|
+
let nearestDistance = Number.POSITIVE_INFINITY;
|
|
435
|
+
for (const placement of snapshot.placements) {
|
|
436
|
+
if (placement.slot < 0) continue;
|
|
437
|
+
live += 1;
|
|
438
|
+
const at = placement.centre;
|
|
439
|
+
const distance = Math.hypot(
|
|
440
|
+
(at[0] as number) - snapshot.camera.x,
|
|
441
|
+
(at[2] as number) - snapshot.camera.z,
|
|
442
|
+
);
|
|
443
|
+
if (Number.isFinite(distance) && distance < nearestDistance) {
|
|
444
|
+
nearestDistance = distance;
|
|
445
|
+
nearest = placement;
|
|
446
|
+
}
|
|
447
|
+
}
|
|
448
|
+
const probe: IValidationProbe = { eye, live, snapshot: snapshot.count };
|
|
449
|
+
if (nearest === undefined) return probe;
|
|
450
|
+
const at = nearest.centre;
|
|
451
|
+
const radius = at[3] as number;
|
|
452
|
+
const centre: readonly [number, number, number] = [
|
|
453
|
+
at[0] as number,
|
|
454
|
+
at[1] as number,
|
|
455
|
+
at[2] as number,
|
|
456
|
+
];
|
|
457
|
+
const root: readonly [number, number, number] = [
|
|
458
|
+
nearest.matrix[12] as number,
|
|
459
|
+
nearest.matrix[13] as number,
|
|
460
|
+
nearest.matrix[14] as number,
|
|
461
|
+
];
|
|
462
|
+
let margin = Number.POSITIVE_INFINITY;
|
|
463
|
+
for (let plane = 0; plane < 6; plane += 1) {
|
|
464
|
+
const offset = plane * 4;
|
|
465
|
+
const signed =
|
|
466
|
+
(snapshot.camera.planes[offset] as number) * (at[0] as number) +
|
|
467
|
+
(snapshot.camera.planes[offset + 1] as number) * (at[1] as number) +
|
|
468
|
+
(snapshot.camera.planes[offset + 2] as number) * (at[2] as number) +
|
|
469
|
+
(snapshot.camera.planes[offset + 3] as number);
|
|
470
|
+
margin = Math.min(margin, signed + radius);
|
|
471
|
+
}
|
|
472
|
+
const numbers = [...centre, ...root, radius, nearestDistance, margin];
|
|
473
|
+
if (numbers.some((value) => !Number.isFinite(value))) return probe;
|
|
474
|
+
const cull = snapshot.slots[nearest.slot]?.cull;
|
|
475
|
+
return {
|
|
476
|
+
...probe,
|
|
477
|
+
nearest: {
|
|
478
|
+
centre,
|
|
479
|
+
distance: nearestDistance,
|
|
480
|
+
margin,
|
|
481
|
+
radius,
|
|
482
|
+
root,
|
|
483
|
+
slot: nearest.slot,
|
|
484
|
+
...(cull === undefined ? {} : { cull }),
|
|
485
|
+
},
|
|
486
|
+
};
|
|
487
|
+
}
|
|
488
|
+
|
|
489
|
+
export function validationReport(input: IGpuSceneComparison): IGpuSceneValidation {
|
|
490
|
+
const blind = input.compared === 0 && input.placed > 0;
|
|
491
|
+
const cause =
|
|
492
|
+
input.deviceError !== ""
|
|
493
|
+
? `device-error ${input.deviceError}`
|
|
494
|
+
: (input.cause ?? (blind ? `compared-0-with-placed=${String(input.placed)}` : ""));
|
|
495
|
+
const verdict: GpuSceneVerdict =
|
|
496
|
+
cause !== ""
|
|
497
|
+
? "error"
|
|
498
|
+
: input.mismatched > 0 || input.matricesMismatched > 0 || input.meshMismatched > 0
|
|
499
|
+
? "mismatch"
|
|
500
|
+
: "ok";
|
|
501
|
+
const memory: string[] = [];
|
|
502
|
+
if (input.memory !== undefined)
|
|
503
|
+
for (const name of MEMORY_FIELDS) {
|
|
504
|
+
const value = input.memory[name];
|
|
505
|
+
if (typeof value === "number" && Number.isFinite(value))
|
|
506
|
+
memory.push(`${name}=${String(value)}`);
|
|
507
|
+
}
|
|
508
|
+
const details = [...memory, ...(input.probe === undefined ? [] : probeFields(input.probe))];
|
|
509
|
+
const suffix = details.length === 0 ? "" : ` ${details.join(" ")}`;
|
|
510
|
+
const line =
|
|
511
|
+
`TN_WORLD_GPU_SCENE_VALIDATE ${verdict} compared=${String(input.compared)} ` +
|
|
512
|
+
`instancesGpu=${String(input.instancesGpu)} instancesCpu=${String(input.instancesCpu)} ` +
|
|
513
|
+
`mismatched=${String(input.mismatched)} matricesMismatched=${String(input.matricesMismatched)} ` +
|
|
514
|
+
`meshMismatched=${String(input.meshMismatched)}${suffix}`;
|
|
515
|
+
const lines: string[] = [...input.mismatches, ...input.matrixMismatches, ...input.meshMismatches];
|
|
516
|
+
if (cause !== "") lines.push(`cause=${cause.slice(0, CAUSE_CHARS)}`);
|
|
517
|
+
return { verdict, line, lines };
|
|
518
|
+
}
|