@threenative/core 0.3.13 → 0.3.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/capabilities.json +299 -10
  2. package/dist/{chunk-4SRAQFTU.js → chunk-2GPHICV6.js} +1 -1
  3. package/dist/{chunk-DIPIJICH.js → chunk-GEMQJBY4.js} +70 -18
  4. package/dist/{chunk-EFWZWLPY.js → chunk-QAMSM3Z5.js} +354 -12
  5. package/dist/{chunk-SV4QVUTQ.js → chunk-QAQHYOWY.js} +1 -1
  6. package/dist/{chunk-EEABDLUC.js → chunk-VBBYWGAT.js} +2 -2
  7. package/dist/{chunk-GYUZJQ7U.js → chunk-VQRPEOKY.js} +4 -1
  8. package/dist/index.d.ts +605 -7
  9. package/dist/index.js +1973 -609
  10. package/dist/playtest.js +3 -3
  11. package/dist/{quality-BYqKGAwo.d.ts → quality-BADStsTn.d.ts} +2 -2
  12. package/dist/render-environment.d.ts +1 -1
  13. package/dist/ui-layer.js +2 -2
  14. package/dist/worker.js +2 -2
  15. package/dist/world.d.ts +13 -3
  16. package/dist/world.js +179 -36
  17. package/mcp/animation-server.mjs +1 -1
  18. package/mcp/engine-server.mjs +32 -6
  19. package/mcp/servers.mjs +3 -3
  20. package/package.json +5 -5
  21. package/scripts/ensure-mcp.mjs +6 -1
  22. package/src/clustered-batch.ts +146 -3
  23. package/src/clustered-mesh.ts +548 -20
  24. package/src/debug.ts +16 -0
  25. package/src/displaced-surface.ts +428 -0
  26. package/src/frame-budget.ts +16 -0
  27. package/src/generated/console-markers.ts +1 -0
  28. package/src/grass-field.ts +628 -0
  29. package/src/index.ts +112 -0
  30. package/src/render/material-key.ts +21 -1
  31. package/src/render/screen-probe-gather.ts +303 -0
  32. package/src/render/short-range-ao.ts +274 -0
  33. package/src/render/world-impostor-surface.ts +98 -3
  34. package/src/render-camera-cull.ts +9 -3
  35. package/src/renderer.ts +26 -4
  36. package/src/scatter-field.ts +496 -0
  37. package/src/startup-offscreen-bytes.ts +11 -5
  38. package/src/state.ts +16 -3
  39. package/src/static-transform.ts +75 -6
  40. package/src/tile-ring.ts +294 -0
  41. package/src/version.ts +1 -1
  42. package/src/warmup.ts +15 -2
  43. package/src/world-cell-batches.ts +4 -0
  44. package/src/world-cell-data.ts +7 -0
  45. package/src/world-cell-models.ts +36 -8
  46. package/src/world-cell-render-gpu-dress.ts +4 -2
  47. package/src/world-cell-render-util.ts +2 -2
  48. package/src/world-cells.ts +1 -1
  49. package/src/world-river-ribbon.ts +13 -22
  50. package/src/world-water-bodies.ts +113 -3
@@ -0,0 +1,274 @@
1
+ import {
2
+ Break,
3
+ Fn,
4
+ If,
5
+ Loop,
6
+ clamp,
7
+ cos,
8
+ float,
9
+ floor,
10
+ int,
11
+ length,
12
+ max,
13
+ normalize,
14
+ pow,
15
+ rtt,
16
+ sin,
17
+ uniform,
18
+ uv,
19
+ vec2,
20
+ vec3,
21
+ vec4,
22
+ } from "three/tsl";
23
+ import type { Node, TextureNode } from "three/webgpu";
24
+
25
+ /** The marker the pass prints once, with the sweep it ran. */
26
+ export const SHORT_RANGE_AO_MARKER = "TN_SHORT_RANGE_AO";
27
+
28
+ /** Half-hemisphere sweeps around the view normal (Unreal's `ShortRangeAO.HorizonSearchSliceCount`, 2 at Epic). */
29
+ const SLICE_COUNT = 2;
30
+ /** Samples per sweep, at the squared step fraction (Unreal's `HorizonSearchStepCount`, 3 at Epic). */
31
+ const STEP_COUNT = 3;
32
+ /**
33
+ * Metres the search would cover in the world at the display height, as Unreal states it: twice the screen probe
34
+ * downsample factor, 2 x 16 px (`r.Lumen.ScreenProbeGather.ShortRangeAO`, LumenScreenProbeGather.cpp:2665).
35
+ */
36
+ const REACH_PX = 32;
37
+ /** The most sweeps the loops may run, so a driver cannot unroll them into a program too large to compile. */
38
+ const MAX_SLICES = 8;
39
+ const MAX_STEPS = 8;
40
+ /** A sample this close to the pixel says nothing about a horizon. */
41
+ const MIN_DISTANCE = 1e-5;
42
+ const HALF_FLOAT_TYPE = 1016;
43
+
44
+ /** The scene camera the pass reads: a projection to map the screen and a depth to come back to view space. */
45
+ export interface IShortRangeAOCamera {
46
+ readonly projectionMatrix: { readonly elements: readonly number[] };
47
+ }
48
+
49
+ export interface IShortRangeAOOptions {
50
+ /** The camera the scene pass drew with: a post quad's own camera nodes are the quad's, not the scene's. */
51
+ readonly camera: IShortRangeAOCamera;
52
+ /** The drawing buffer, in pixels. The search's reach is a distance on the screen, so it needs the size. */
53
+ readonly viewport: { readonly width: number; readonly height: number };
54
+ /** Sweeps around the view normal (`horizonSearchSliceCount`): 2, Unreal's Epic setting. */
55
+ readonly horizonSearchSliceCount?: number;
56
+ /** Samples per sweep (`horizonSearchStepCount`): 3, Unreal's Epic setting. */
57
+ readonly horizonSearchStepCount?: number;
58
+ /** The reach in pixels of the drawing buffer: 32, twice Unreal's 16 px screen probe downsample. */
59
+ readonly reachPx?: number;
60
+ /**
61
+ * Whether the pass also answers the bent normal (`.rgb`), Unreal's Epic-only setting. The occlusion alone is
62
+ * `.a`, so a composite that does not read a bent normal pays one channel, not a second pass.
63
+ */
64
+ readonly bentNormal?: boolean;
65
+ /** How strongly the occlusion applies: 1 keeps the horizon's own answer. */
66
+ readonly intensity?: number;
67
+ /** False silences the `TN_SHORT_RANGE_AO` line, not the report. */
68
+ readonly marker?: boolean;
69
+ }
70
+
71
+ /** What the pass swept, printed once and readable by a tool. */
72
+ export interface IShortRangeAOReport {
73
+ readonly horizonSearchSliceCount: number;
74
+ readonly horizonSearchStepCount: number;
75
+ readonly reachPx: number;
76
+ /** Samples each pixel's normal hemisphere took: slices x steps. */
77
+ readonly samplesPerPixel: number;
78
+ readonly bentNormal: boolean;
79
+ }
80
+
81
+ /**
82
+ * Unreal's Short Range AO (PRD-640 Phase 3): a horizon search of `horizonSearchSliceCount` sweeps around the view
83
+ * normal, `horizonSearchStepCount` samples each at the squared fraction of a screen-space reach, at full resolution,
84
+ * with a bent normal at Epic. It is the AO that runs *with* dynamic GI: the contact detail Lumen keeps after the screen
85
+ * probe gather has already answered the wide occlusion, so the frame is not darkened twice by two wide treatments
86
+ * (UE 5.8.3: Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenSpaceBentNormal.cpp and
87
+ * Engine/Shaders/Private/Lumen/LumenScreenSpaceBentNormal.usf). GTAO through `ambientOcclusion` stays the AO of the
88
+ * tiers without dynamic GI.
89
+ *
90
+ * The result is one texture: `rgb` the bent normal in view space (the space the normal target and the GI gather work
91
+ * in), `a` the share of the hemisphere left open, which multiplies *indirect* light only — direct light and emission
92
+ * keep their own occlusion, as Unreal's `DiffuseIndirectComposite` applies it. Multi-bounce and the albedo cap belong
93
+ * to the game's composite, because they decide how a surface looks.
94
+ */
95
+ export class ShortRangeAO {
96
+ readonly report: IShortRangeAOReport;
97
+ readonly horizonSearchSliceCount: number;
98
+ readonly horizonSearchStepCount: number;
99
+ readonly reachPx: number;
100
+ readonly bentNormal: boolean;
101
+ readonly intensity: number;
102
+ readonly #camera: IShortRangeAOCamera;
103
+ readonly #viewport: { readonly width: number; readonly height: number };
104
+
105
+ constructor(options: IShortRangeAOOptions) {
106
+ const horizonSearchSliceCount = options.horizonSearchSliceCount ?? SLICE_COUNT;
107
+ const horizonSearchStepCount = options.horizonSearchStepCount ?? STEP_COUNT;
108
+ const reachPx = options.reachPx ?? REACH_PX;
109
+ const intensity = options.intensity ?? 1;
110
+ if (!(Number.isInteger(horizonSearchSliceCount) && horizonSearchSliceCount >= 1))
111
+ throw new RangeError(
112
+ `TN_SHORT_RANGE_AO: horizonSearchSliceCount ${horizonSearchSliceCount} must be a whole number of sweeps, at least 1`,
113
+ );
114
+ if (!(Number.isInteger(horizonSearchStepCount) && horizonSearchStepCount >= 1))
115
+ throw new RangeError(
116
+ `TN_SHORT_RANGE_AO: horizonSearchStepCount ${horizonSearchStepCount} must be a whole number of samples, at least 1`,
117
+ );
118
+ if (horizonSearchSliceCount > MAX_SLICES || horizonSearchStepCount > MAX_STEPS)
119
+ throw new RangeError(
120
+ `TN_SHORT_RANGE_AO: a sweep of ${horizonSearchSliceCount} x ${horizonSearchStepCount} is more than the pass compiles (${MAX_SLICES} x ${MAX_STEPS})`,
121
+ );
122
+ if (!(reachPx > 0))
123
+ throw new RangeError(
124
+ `TN_SHORT_RANGE_AO: reachPx ${reachPx} must be pixels of the drawing buffer beyond 0`,
125
+ );
126
+ if (!(intensity > 0))
127
+ throw new RangeError(`TN_SHORT_RANGE_AO: intensity ${intensity} must be beyond 0`);
128
+ if (!(options.viewport.width > 0 && options.viewport.height > 0))
129
+ throw new RangeError(
130
+ `TN_SHORT_RANGE_AO: viewport ${options.viewport.width}x${options.viewport.height} must be the drawing buffer`,
131
+ );
132
+ if (options.camera?.projectionMatrix === undefined)
133
+ throw new TypeError(
134
+ "TN_SHORT_RANGE_AO_CAMERA: the pass needs the scene camera's projectionMatrix",
135
+ );
136
+ this.horizonSearchSliceCount = horizonSearchSliceCount;
137
+ this.horizonSearchStepCount = horizonSearchStepCount;
138
+ this.reachPx = reachPx;
139
+ this.bentNormal = options.bentNormal ?? true;
140
+ this.intensity = intensity;
141
+ this.#camera = options.camera;
142
+ this.#viewport = options.viewport;
143
+ this.report = {
144
+ horizonSearchSliceCount,
145
+ horizonSearchStepCount,
146
+ reachPx,
147
+ samplesPerPixel: horizonSearchSliceCount * horizonSearchStepCount,
148
+ bentNormal: this.bentNormal,
149
+ };
150
+ if (options.marker !== false)
151
+ console.info(`${SHORT_RANGE_AO_MARKER} ${JSON.stringify(this.report)}`);
152
+ }
153
+
154
+ /**
155
+ * The occlusion of one frame: `rgb` the bent normal in view space, `a` the share of the hemisphere left open. `depth`
156
+ * is the scene pass's depth target and `normal` its view-space normal target.
157
+ */
158
+ occlusion(depthNode: TextureNode, normalNode: TextureNode): Node<"vec4"> {
159
+ const element = (index: number): Node<"float"> =>
160
+ uniform(this.#camera.projectionMatrix.elements[index] ?? 0).onRenderUpdate(
161
+ () => this.#camera.projectionMatrix.elements[index] ?? 0,
162
+ ) as Node<"float">;
163
+ const [p0, p5, p8, p9, p10, p14] = [0, 5, 8, 9, 10, 14].map(element) as [
164
+ Node<"float">,
165
+ Node<"float">,
166
+ Node<"float">,
167
+ Node<"float">,
168
+ Node<"float">,
169
+ Node<"float">,
170
+ ];
171
+ // Depth is (A z + B) / -z, so z = -B / (depth + A): the same mapping the gather and the reflections use.
172
+ const viewPosition = (coordinate: Node<"vec2">, depth: Node<"float">): Node<"vec3"> => {
173
+ const z = p14.negate().div(depth.add(p10));
174
+ const ndc = vec2(coordinate.x.mul(2).sub(1), float(1).sub(coordinate.y).mul(2).sub(1));
175
+ return vec3(z.negate().mul(ndc.x.add(p8)).div(p0), z.negate().mul(ndc.y.add(p9)).div(p5), z);
176
+ };
177
+ const slices = uniform(this.horizonSearchSliceCount);
178
+ const steps = uniform(this.horizonSearchStepCount);
179
+ // The reach is a distance on the screen, so one step is that many pixels of the drawing buffer, in uv.
180
+ const stepOffset = vec2(
181
+ this.reachPx / this.#viewport.width,
182
+ this.reachPx / this.#viewport.height,
183
+ );
184
+ const intensity = uniform(this.intensity);
185
+ const bent = this.bentNormal;
186
+
187
+ const graph = Fn(() => {
188
+ const coordinate = uv();
189
+ const result = vec4(0, 0, 1, 1).toVar();
190
+ const centreDepth = depthNode.sample(coordinate).r;
191
+ const centreNormal = normalNode.sample(coordinate).xyz;
192
+ // The sky and a draw the normal pass skips (an unlit material) take no occlusion.
193
+ If(centreDepth.lessThan(1).and(centreNormal.dot(centreNormal).greaterThan(0.25)), () => {
194
+ const position = viewPosition(coordinate, centreDepth);
195
+ const normal = normalize(centreNormal);
196
+ // A frame around the normal, so a sweep turns in the surface's tangent plane.
197
+ const helper = normal.y
198
+ .abs()
199
+ .lessThan(0.99)
200
+ .select(vec3(0, 1, 0), vec3(1, 0, 0));
201
+ const tangent = normalize(helper.cross(normal));
202
+ const bitangent = normal.cross(tangent);
203
+ // Each pixel turns its sweeps by its own angle (interleaved gradient noise on a fixed lattice of the uv), so
204
+ // two sweeps do not leave the pattern of the sweep set on the frame.
205
+ const cell = coordinate.mul(2048).floor();
206
+ const noise = cell.x
207
+ .mul(0.06711056)
208
+ .add(cell.y.mul(0.00583715))
209
+ .fract()
210
+ .mul(52.9829189)
211
+ .fract();
212
+ const open = float(0).toVar();
213
+ const direction = vec3(0, 0, 1).toVar();
214
+ const bentNormal = vec3(0, 0, 0).toVar();
215
+ Loop(
216
+ { start: int(0), end: int(MAX_SLICES), type: "int", condition: "<" },
217
+ ({ i: slice }) => {
218
+ If(float(slice).greaterThanEqual(slices), () => {
219
+ Break();
220
+ });
221
+ const angle = float(slice).add(noise).div(slices).mul(Math.PI);
222
+ direction.assign(normalize(tangent.mul(cos(angle)).add(bitangent.mul(sin(angle)))));
223
+ // The horizon starts at the surface itself: nothing beyond it is above the plane.
224
+ const horizon = float(-1).toVar();
225
+ Loop(
226
+ { start: int(0), end: int(MAX_STEPS), type: "int", condition: "<" },
227
+ ({ i: step }) => {
228
+ If(float(step).greaterThanEqual(steps), () => {
229
+ Break();
230
+ });
231
+ // Unreal lands each step at the squared step fraction of the reach (LumenScreenSpaceBentNormal.usf:355).
232
+ const fraction = float(step).add(1).div(steps);
233
+ const sampleCoordinate = coordinate.add(
234
+ stepOffset.mul(direction.xy).mul(fraction.mul(fraction)),
235
+ );
236
+ const sampleDepth = depthNode.sample(sampleCoordinate).r;
237
+ const inside = sampleCoordinate.x
238
+ .greaterThanEqual(0)
239
+ .and(sampleCoordinate.x.lessThanEqual(1))
240
+ .and(sampleCoordinate.y.greaterThanEqual(0))
241
+ .and(sampleCoordinate.y.lessThanEqual(1))
242
+ .and(sampleDepth.lessThan(1));
243
+ const delta = viewPosition(sampleCoordinate, sampleDepth).sub(position);
244
+ // How far above the tangent plane the sample stands: its sine, which is the horizon's angle.
245
+ const sine = delta.dot(normal).div(max(length(delta), float(MIN_DISTANCE)));
246
+ horizon.assign(max(horizon, inside.select(sine, float(-1))));
247
+ },
248
+ );
249
+ const kept = clamp(float(1).sub(max(horizon, float(0))), float(0), float(1));
250
+ open.assign(open.add(kept));
251
+ if (bent)
252
+ bentNormal.assign(
253
+ bentNormal.add(direction.mul(kept)).add(normal.mul(kept.mul(0.5).add(0.25))),
254
+ );
255
+ },
256
+ );
257
+ const visibility = pow(clamp(open.div(slices), float(0), float(1)), intensity);
258
+ // A bent normal alone can point along the geometric one or degenerate in a fully open pixel: adding the
259
+ // geometric normal and normalising once keeps the axis well behaved at both ends.
260
+ const axis = bent ? normalize(normalize(bentNormal).add(normal)) : normal;
261
+ result.assign(vec4(axis, visibility));
262
+ });
263
+ return result;
264
+ })();
265
+
266
+ const node = rtt(graph, null, null, { type: HALF_FLOAT_TYPE });
267
+ return Object.defineProperties(node, {
268
+ bentNormal: { value: bent },
269
+ reachPx: { value: this.reachPx },
270
+ slices: { value: this.horizonSearchSliceCount },
271
+ steps: { value: this.horizonSearchStepCount },
272
+ }) as Node<"vec4">;
273
+ }
274
+ }
@@ -41,6 +41,7 @@ import {
41
41
  modelWorldMatrix,
42
42
  normalize,
43
43
  positionGeometry,
44
+ renderGroup,
44
45
  screenCoordinate,
45
46
  select,
46
47
  sin,
@@ -64,6 +65,7 @@ import {
64
65
  type NodeBuilder,
65
66
  type NodeMaterial,
66
67
  } from "three/webgpu";
68
+ import { readLaunchFlag } from "../debug.js";
67
69
  import { IMPOSTOR_VIEW_GRID, type WorldImpostorAtlas } from "./world-impostor.js";
68
70
 
69
71
  type InstanceMatrixFn = () => Node<"mat4">;
@@ -967,6 +969,82 @@ export function advanceTemporalLod(
967
969
  state.alpha = window > 0 ? Math.min(1, Math.max(0, (now - lag - state.fromTime) / window)) : 1;
968
970
  }
969
971
 
972
+ /**
973
+ * The distance past which `level`'s gate discards every fragment at the worst per-instance random
974
+ * draw: `worldLodMaterial`'s fade-out mix reaches 1 at `gate + 0.75 * span` (0.5 of the ramp plus
975
+ * the 0.25 random swing). `undefined` for the last level, which has no coarser level to fade into.
976
+ */
977
+ export function lodFadedPast(
978
+ distances: readonly number[],
979
+ level: number,
980
+ width: number,
981
+ ): number | undefined {
982
+ const gate = level + 1;
983
+ const at = distances[gate];
984
+ if (at === undefined) return undefined;
985
+ let span = Math.min(at * width, (at - (distances[gate - 1] as number)) * width);
986
+ const next = distances[gate + 1];
987
+ if (next !== undefined) span = Math.min(span, (next - at) * width);
988
+ return at + 0.75 * span;
989
+ }
990
+
991
+ // `?lodCollapse=1` (TN_LOD_COLLAPSE, `__tnLodCollapse`) is read once per page; while it is on,
992
+ // `globalThis.__tnLodCollapse = false` turns the collapse off live for a paired A/B.
993
+ let lodCollapseArmed: boolean | undefined;
994
+ // Render group, as the LOD clock: an object-group uniform freezes on settled static batches.
995
+ const makeLodCollapseSwitch = () => uniform(1).setGroup(renderGroup);
996
+ let lodCollapseSwitch: ReturnType<typeof makeLodCollapseSwitch> | undefined;
997
+ function lodCollapseNode(): ReturnType<typeof makeLodCollapseSwitch> | undefined {
998
+ lodCollapseArmed ??= readLaunchFlag({
999
+ environment: "TN_LOD_COLLAPSE",
1000
+ query: "lodCollapse",
1001
+ global: "__tnLodCollapse",
1002
+ });
1003
+ if (!lodCollapseArmed) return undefined;
1004
+ lodCollapseSwitch ??= makeLodCollapseSwitch();
1005
+ return lodCollapseSwitch;
1006
+ }
1007
+
1008
+ /** Per frame: follow `globalThis.__tnLodCollapse` when the collapse was armed at boot. */
1009
+ export function syncLodCollapse(): void {
1010
+ if (lodCollapseSwitch === undefined) return;
1011
+ const live: unknown = Reflect.get(globalThis, "__tnLodCollapse");
1012
+ if (typeof live === "boolean") lodCollapseSwitch.value = live ? 1 : 0;
1013
+ }
1014
+
1015
+ /**
1016
+ * Collapse to one point the vertices of an instance whose every fragment the LOD gate discards:
1017
+ * past `past` from every eye the masks read, and not held whole by its published range or a swap.
1018
+ */
1019
+ function collapseFadedVertices(
1020
+ material: NodeMaterial,
1021
+ on: Node<"float">,
1022
+ gate: {
1023
+ readonly past: Node<"float">;
1024
+ readonly distances: readonly Node<"float">[];
1025
+ readonly lod: Node<"float">;
1026
+ readonly publishedRanges: boolean;
1027
+ readonly clock: Node<"float"> | undefined;
1028
+ },
1029
+ ): void {
1030
+ let faded = on.greaterThan(0.5);
1031
+ for (const distance of gate.distances) faded = faded.and(distance.greaterThanEqual(gate.past));
1032
+ if (gate.publishedRanges) {
1033
+ // A record whole at this level (`.y <= lod`) or still holding it after a swap draws anyway.
1034
+ const range = attribute("tnPublishedLodRange", "vec4") as Node<"vec4">;
1035
+ faded = faded.and(range.y.greaterThan(gate.lod));
1036
+ if (gate.clock !== undefined)
1037
+ faded = faded.and(
1038
+ range.z
1039
+ .lessThan(0)
1040
+ .or(gate.clock.sub(range.w).div(LOD_TEMPORAL_LAG).greaterThanEqual(1))
1041
+ .or(range.z.sub(gate.lod).abs().greaterThanEqual(0.5)),
1042
+ );
1043
+ }
1044
+ const position = (material.positionNode ?? positionGeometry) as Node<"vec3">;
1045
+ material.positionNode = select(faded, vec3(0, 0, 0), position);
1046
+ }
1047
+
970
1048
  /** Complementary LOD masks over the caller's distance bands, shared by colour and shadow passes. */
971
1049
  export function worldLodMaterial(
972
1050
  source: Material,
@@ -995,9 +1073,11 @@ export function worldLodMaterial(
995
1073
  .mul(vec4(0, 0, 0, 1)).xyz,
996
1074
  )();
997
1075
  // Quantise recovered roots so part-local float rounding cannot change the instance hash.
998
- const origin = varying(floor(root.mul(16).add(0.5)).div(16));
999
- const distanceTo = (at: Node<"vec3">) =>
1000
- (spatial ? length(origin.sub(at)) : length(origin.xz.sub(at.xz))).mul(distanceBias);
1076
+ const quantised = floor(root.mul(16).add(0.5)).div(16);
1077
+ const origin = varying(quantised);
1078
+ const distanceFrom = (point: Node<"vec3">, at: Node<"vec3">) =>
1079
+ (spatial ? length(point.sub(at)) : length(point.xz.sub(at.xz))).mul(distanceBias);
1080
+ const distanceTo = (at: Node<"vec3">) => distanceFrom(origin, at);
1001
1081
  const distance = distanceTo(eye);
1002
1082
  const random = fract(sin(dot(origin.xz, vec2(12.9898, 78.233))).mul(43758.5453));
1003
1083
  const noise = fract(sin(dot(floor(screenCoordinate.xy), vec2(12.9898, 78.233))).mul(43758.5453));
@@ -1079,6 +1159,21 @@ export function worldLodMaterial(
1079
1159
  material.maskShadowNode = material.maskShadowNode
1080
1160
  ? (material.maskShadowNode as Node<"bool">).and(shadow)
1081
1161
  : shadow;
1162
+ // PRD-888 lever 2: an instance past `lodFadedPast` has every colour and shadow fragment of this
1163
+ // level discarded, so its vertices collapse to one point and the rasteriser drops the triangles.
1164
+ // Read per instance in the vertex stage with the worst random draw and a 0.1 % margin, so the
1165
+ // varying's rounding cannot flip a fragment the gate would have drawn.
1166
+ const collapseOn = lodCollapseNode();
1167
+ if (collapseOn !== undefined)
1168
+ collapseFadedVertices(material, collapseOn, {
1169
+ past: uniform((lodFadedPast(distances, level, width) ?? 1e30) * 1.001),
1170
+ distances: (temporal === undefined ? [eye] : [eye, temporal.from, temporal.to]).map((at) =>
1171
+ distanceFrom(quantised, at),
1172
+ ),
1173
+ lod,
1174
+ publishedRanges,
1175
+ clock,
1176
+ });
1082
1177
  if (publishedRanges) material.userData.tnPublishedLodRange = true;
1083
1178
  return material;
1084
1179
  }
@@ -269,10 +269,10 @@ function hierarchyRevision(object: Object3D): number | undefined {
269
269
  * Counts one costly step by name in `globalThis.__tnEngineCost`, the bag a playtest reads per frame
270
270
  * (core reports it per frame in TN_FRAME_BUDGET.counters.engine), so a kit that brings back a per-frame walk fails its bound.
271
271
  */
272
- function countEngineCost(name: string): void {
272
+ function countEngineCost(name: string, count = 1): void {
273
273
  const host = globalThis as { __tnEngineCost?: Record<string, number> };
274
274
  host.__tnEngineCost ??= {};
275
- host.__tnEngineCost[name] = (host.__tnEngineCost[name] ?? 0) + 1;
275
+ host.__tnEngineCost[name] = (host.__tnEngineCost[name] ?? 0) + count;
276
276
  }
277
277
 
278
278
  /**
@@ -473,7 +473,13 @@ export class RenderCameraCull {
473
473
  this.#animationFrame += 1;
474
474
  this.#animationPrepared = true;
475
475
  this.#prepareCamera(camera, viewportHeight);
476
- if (this.#bandOnEngine(root, camera) || !this.#prepareAnimated()) return;
476
+ if (this.#bandOnEngine(root, camera)) {
477
+ // The engine bands every rig, so the JS rig cache rebuilds nothing: a measured 0, which the kit
478
+ // contract's per-window bound needs, never a missing counter.
479
+ countEngineCost("cullRigRebuilds", 0);
480
+ return;
481
+ }
482
+ if (!this.#prepareAnimated()) return;
477
483
  // Start at each rig and each stand-in that observes one, never at the scene: the walk then visits
478
484
  // the same objects a scene walk would have acted on, and nothing else.
479
485
  const rootShown = this.#isVisibleInWorld(root as Object3D);
package/src/renderer.ts CHANGED
@@ -1340,6 +1340,9 @@ function wrapRenderer(
1340
1340
  prepareTextures: async (textures, signal, onProgress, replacements) => {
1341
1341
  if (disposed) throw new Error("Renderer disposed during texture preparation.");
1342
1342
  if (kind !== "webgpu") return 0;
1343
+ // The owned engine keeps compressed mip bytes in its own heap and uploads them itself: its
1344
+ // texture facade shows no CPU mips, so there is nothing here to stage, and no work to report.
1345
+ if ((raw.info as { engine?: unknown } | undefined)?.engine !== undefined) return 0;
1343
1346
  // Snapshot the caller's iterable once. An owned replacement resolves back to its original,
1344
1347
  // so a repeated call that hands back a published replacement keeps a stable identity instead
1345
1348
  // of looking like an unrelated texture and returning stale work.
@@ -2110,6 +2113,9 @@ export async function createRenderer(options: IRendererOptions = {}): Promise<IR
2110
2113
  // Why WebGPU did not start, when it was tried: the boot failure must name it, or a fault in the
2111
2114
  // WebGPU path (PRD-752: a DOM-only canvas call in a worker) reads as a device without WebGPU.
2112
2115
  let webgpuFailure: string | undefined;
2116
+ // The instance the WebGPU attempt built, held outside the try: a start that failed in `init()`
2117
+ // keeps it, and a facade that failed still holds the page's one renderer slot until it is released.
2118
+ let opening: RendererInstance | undefined;
2113
2119
 
2114
2120
  if (preferWebGPU && (source?.hasWebGPU() ?? "gpu" in (globalThis.navigator ?? {}))) {
2115
2121
  try {
@@ -2125,6 +2131,7 @@ export async function createRenderer(options: IRendererOptions = {}): Promise<IR
2125
2131
  });
2126
2132
  });
2127
2133
  const instance = raw as RendererInstance;
2134
+ opening = instance;
2128
2135
  await instance.init?.();
2129
2136
  // A game that sets `toneMapping` on the renderer later (WorldEnvironment, Daylight) replaces this.
2130
2137
  applyRendererToneMapping(instance, options.toneMapping ?? "filmic", report);
@@ -2149,10 +2156,25 @@ export async function createRenderer(options: IRendererOptions = {}): Promise<IR
2149
2156
  if (adapter.gpuClass !== undefined)
2150
2157
  report(`${GPU_CLASS_MARKER}:${JSON.stringify(adapter.gpuClass)}`);
2151
2158
  } catch (error) {
2152
- // A facade and Wasm engine from two builds is an install fault, not a device without
2153
- // WebGPU: falling back would report TN_NO_RENDERER and hide the fix.
2154
- if (error instanceof Error && error.message.startsWith("TN_WASM_ABI_MISMATCH")) throw error;
2155
- webgpuFailure = error instanceof Error ? error.message : String(error);
2159
+ // Release the page's one slot before anything else: a renderer that failed to start still
2160
+ // holds it, so the next start in this page (a hot reload) threw TN_WASM_RENDERER_SINGLE and
2161
+ // hid this failure.
2162
+ try {
2163
+ opening?.dispose?.();
2164
+ } catch {
2165
+ // A half-started renderer may refuse to release; the fallback still has to be built.
2166
+ }
2167
+ // The engine names its own refusals: a TN_WASM_, TN_NATIVE_ or TN_ABI_ code is a fault in the
2168
+ // game's own code or its install (a background it cannot draw, a facade and Wasm engine from
2169
+ // two builds), and reporting it as a device without WebGPU hides the fix. A device that cannot
2170
+ // start is the one case TN_NO_RENDERER is for, and its reason already rides along in that
2171
+ // message, so the adapter, device, lost device, surface and init codes keep the fallback. The
2172
+ // code ends where its message does, so TN_WASM_INIT_TEXTURE and TN_WASM_DEVICE_ERROR stay the
2173
+ // content faults they are.
2174
+ const message = error instanceof Error ? error.message : String(error);
2175
+ const deviceFault = /^TN_WASM_(?:DEVICE_LOST|DEVICE|ADAPTER|SURFACE|INIT):/u;
2176
+ if (/^TN_(?:WASM|NATIVE|ABI)_/u.test(message) && !deviceFault.test(message)) throw error;
2177
+ webgpuFailure = message;
2156
2178
  renderer = undefined;
2157
2179
  }
2158
2180
  }