@threenative/core 0.3.5 → 0.3.8

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 (137) hide show
  1. package/README.md +3 -5
  2. package/capabilities.json +739 -50
  3. package/dist/{assets-CqvE429w.d.ts → assets-YUbXa3-Y.d.ts} +101 -2
  4. package/dist/{canvas-layer-C1-5CviZ.d.ts → canvas-layer-vCtanIeB.d.ts} +1 -1
  5. package/dist/{game-Bj8G1wmD.d.ts → game-cb99J-YE.d.ts} +112 -31
  6. package/dist/hot.d.ts +4 -4
  7. package/dist/hot.js +23 -5
  8. package/dist/index.d.ts +1742 -29
  9. package/dist/index.js +22445 -12411
  10. package/dist/{model-lod-BDAUYgsS.d.ts → model-lod-CTpZ6imz.d.ts} +1 -1
  11. package/dist/net.js +39 -12
  12. package/dist/playtest.d.ts +4 -4
  13. package/dist/playtest.js +59 -10
  14. package/dist/react-css.js +23 -0
  15. package/dist/react.d.ts +2 -2
  16. package/dist/{renderer-9yEo9hPa.d.ts → renderer-rZm0hVqq.d.ts} +178 -5
  17. package/dist/ui-layer.d.ts +11 -2
  18. package/dist/ui-layer.js +76 -4
  19. package/dist/worker.d.ts +36 -0
  20. package/dist/worker.js +1088 -0
  21. package/dist/world.d.ts +11 -3
  22. package/dist/world.js +1117 -197
  23. package/mcp/animation-server.mjs +265 -0
  24. package/mcp/animation.mjs +22 -0
  25. package/mcp/call.mjs +105 -0
  26. package/mcp/devtools.mjs +5 -0
  27. package/mcp/engine-server.mjs +713 -37
  28. package/mcp/launch.mjs +3 -2
  29. package/mcp/servers.d.mts +2 -0
  30. package/mcp/servers.mjs +33 -8
  31. package/package.json +12 -8
  32. package/patches/three@0.185.1-prd269-upgrade.patch +308 -0
  33. package/patches/three@0.185.1.patch +481 -272
  34. package/src/animation-packet-state.ts +88 -0
  35. package/src/animation-pose-packet.ts +537 -0
  36. package/src/animation.ts +779 -31
  37. package/src/asset-cache.ts +719 -0
  38. package/src/assets.ts +521 -152
  39. package/src/audio.ts +29 -3
  40. package/src/auto-batch.ts +792 -0
  41. package/src/config.ts +2 -0
  42. package/src/frame-budget.ts +268 -2
  43. package/src/game.ts +544 -106
  44. package/src/grounding.ts +7 -6
  45. package/src/hot.ts +19 -5
  46. package/src/index.ts +381 -6
  47. package/src/input.ts +21 -2
  48. package/src/interpolation.ts +19 -1
  49. package/src/launch-diagnostics.ts +7 -2
  50. package/src/look/ao-multibounce.ts +29 -0
  51. package/src/look/ao-reach.ts +39 -0
  52. package/src/look/auto-exposure.ts +264 -0
  53. package/src/look/default-tone-mapping.ts +44 -0
  54. package/src/look/exposure-graph.ts +208 -0
  55. package/src/look/exposure-readback.ts +97 -0
  56. package/src/look/exposure-settings.ts +132 -0
  57. package/src/look/filmic-tone-mapping.ts +852 -0
  58. package/src/look/gi-registry.ts +55 -0
  59. package/src/look/local-exposure.ts +507 -0
  60. package/src/look/look-diagnostics.ts +24 -0
  61. package/src/look/motion-blur.ts +42 -0
  62. package/src/look/quality.ts +309 -0
  63. package/src/look/reflection-trace.ts +344 -0
  64. package/src/look/unreal-bloom.ts +295 -0
  65. package/src/look/vignette.ts +14 -0
  66. package/src/look/world-environment.ts +2033 -0
  67. package/src/loop.ts +40 -6
  68. package/src/merge-parts.ts +25 -10
  69. package/src/model-lod.ts +14 -0
  70. package/src/net-session.ts +58 -14
  71. package/src/ocean/spectral.ts +41 -7
  72. package/src/picking.ts +72 -5
  73. package/src/platform.ts +29 -1
  74. package/src/playtest.ts +69 -12
  75. package/src/profiling/FrameCounters.ts +166 -5
  76. package/src/profiling/FrameStages.ts +289 -0
  77. package/src/profiling/Spans.ts +39 -25
  78. package/src/profiling/debug-telemetry.ts +312 -0
  79. package/src/profiling/scene-warning.ts +42 -6
  80. package/src/projection-apply.ts +11 -3
  81. package/src/projection-content.ts +189 -0
  82. package/src/projection-marker.ts +6 -2
  83. package/src/projection-plan.ts +279 -28
  84. package/src/projection-skinned.ts +620 -5
  85. package/src/projection-stability.ts +16 -0
  86. package/src/projection-uniform.ts +5 -1
  87. package/src/quiet-markers.ts +56 -0
  88. package/src/render/budget-ladder.ts +256 -0
  89. package/src/render/chain.ts +89 -7
  90. package/src/render/exposure-units.ts +59 -0
  91. package/src/render/frame-time-budget.ts +162 -0
  92. package/src/render/gi-budget.ts +231 -0
  93. package/src/render/gi-visualize.ts +49 -0
  94. package/src/render/material-key.ts +1 -0
  95. package/src/render/probe-volume.ts +196 -36
  96. package/src/render/rough-diffuse.ts +177 -0
  97. package/src/render/scene-trace.ts +532 -0
  98. package/src/render/shadow-filter-budget.ts +237 -0
  99. package/src/render/sky-capture.ts +194 -0
  100. package/src/render/soft-shadow.ts +607 -0
  101. package/src/render/surface-cache.ts +418 -0
  102. package/src/render/traced-reflections.ts +408 -0
  103. package/src/render/two-sided-foliage.ts +120 -0
  104. package/src/render/virtual-shadow-pages.ts +112 -12
  105. package/src/render/virtual-shadow.ts +386 -38
  106. package/src/render-camera-cull.ts +536 -31
  107. package/src/render-pass-budget.ts +140 -22
  108. package/src/renderProjection.ts +65 -9
  109. package/src/renderer-config.ts +3 -2
  110. package/src/renderer.ts +289 -14
  111. package/src/resolution-scaler.ts +65 -7
  112. package/src/skeletal-mesh.ts +4 -0
  113. package/src/snow-field.ts +46 -0
  114. package/src/softbody.ts +6 -5
  115. package/src/startup-offscreen-bytes.ts +168 -0
  116. package/src/startup-readiness.ts +137 -2
  117. package/src/ui-bridge.ts +38 -0
  118. package/src/ui-hit-regions.ts +6 -2
  119. package/src/ui-layer.ts +1 -0
  120. package/src/ui-state.ts +32 -3
  121. package/src/version.ts +1 -1
  122. package/src/viewport.ts +8 -5
  123. package/src/warmup.ts +76 -10
  124. package/src/worker-audio.ts +579 -0
  125. package/src/worker.ts +842 -0
  126. package/src/world-cells.ts +4 -1
  127. package/gpl/LICENSE.GPL +0 -117
  128. package/gpl/convert.py +0 -192
  129. package/gpl/fixtures/make_world_fixture.py +0 -184
  130. package/gpl/recipes/_common.py +0 -180
  131. package/gpl/recipes/bake_ao.py +0 -111
  132. package/gpl/recipes/decimate.py +0 -70
  133. package/gpl/recipes/export_world.py +0 -699
  134. package/gpl/recipes/retarget.py +0 -131
  135. package/gpl/recipes/unwrap.py +0 -71
  136. package/mcp/blender-server.mjs +0 -689
  137. package/mcp/blender.mjs +0 -26
@@ -0,0 +1,162 @@
1
+ /**
2
+ * The frame-period rule that decides when a render cost moves, as Unreal's DynamicRenderScaling does.
3
+ *
4
+ * It compares the whole GPU frame with the frame period, never one stage's milliseconds. A stage
5
+ * reading depends on the GPU clock (the SSGI pass read 6.3 ms at P5 and 2.1 to 3.0 ms at boost on one
6
+ * scene), and the frame period does not. The rule follows UE 5.8.3:
7
+ * `Engine/Source/Runtime/Engine/Private/DynamicResolution.cpp` (the `r.DynamicRes.*` defaults at
8
+ * `:32-103`, the history walk at `:219-330`, the change gate at `:370-390`) and
9
+ * `Engine/Source/Runtime/RenderCore/Private/DynamicRenderScaling.cpp` (`GetTargetedMs`,
10
+ * `EstimateResolutionFactor`, `DoesResolutionChangeEnough`).
11
+ *
12
+ * Measurement and decision only: the caller applies a move and calls `reset()`, because the frames of
13
+ * the old level say nothing about the new one.
14
+ */
15
+
16
+ export type FrameTimeModel = "linear" | "quadratic";
17
+
18
+ export interface IFrameTimeBudgetOptions {
19
+ /** The frame period in milliseconds: `r.DynamicRes.FrameTimeBudget`, such as 1000 / 60. */
20
+ readonly periodMs: number;
21
+ /** The share of the period to keep free: `TargetedGPUHeadRoomPercentage`. Default 0.10. */
22
+ readonly headroom?: number;
23
+ /** Frames kept in the history: `r.DynamicRes.HistorySize`. Default 16. */
24
+ readonly historyFrames?: number;
25
+ /** Weight of frame N-1 against frame N: `r.DynamicRes.FrameWeightExponent`. Default 0.9. */
26
+ readonly frameWeight?: number;
27
+ /** Frames between two changes: `r.DynamicRes.MinResolutionChangePeriod`. Default 8. */
28
+ readonly minChangeFrames?: number;
29
+ /** Consecutive frames over the period that force an immediate drop: `MaxConsecutiveOverBudgetGPUFrameCount`. Default 2. */
30
+ readonly panicFrames?: number;
31
+ /** The smallest move worth a change: `ChangePercentageThreshold`. Default 0.02. */
32
+ readonly changeThreshold?: number;
33
+ /** How cost scales with the lever: pixels are quadratic in the resolution fraction, a throttle is linear. Default quadratic. */
34
+ readonly model?: FrameTimeModel;
35
+ }
36
+
37
+ export type FrameDirection = "down" | "up" | "hold";
38
+
39
+ /** What the rule says about the newest frame. */
40
+ export interface IFrameTimeDecision {
41
+ readonly direction: FrameDirection;
42
+ /** Two or more consecutive frames over the period: the drop skips the change-period gate. */
43
+ readonly panic: boolean;
44
+ /** Weighted estimate of the lever scale the history supports: below 1 the frame is too dear, above 1 it has room. */
45
+ readonly suggested: number | undefined;
46
+ /** Weighted mean frame milliseconds of the frames the rule read. */
47
+ readonly meanMs: number | undefined;
48
+ /** Frames the rule read. */
49
+ readonly frames: number;
50
+ }
51
+
52
+ function positive(value: number, name: string): number {
53
+ if (!Number.isFinite(value) || value <= 0)
54
+ throw new RangeError(
55
+ `FrameTimeBudget ${name} must be a finite number above zero, got ${value}.`,
56
+ );
57
+ return value;
58
+ }
59
+
60
+ export class FrameTimeBudget {
61
+ readonly periodMs: number;
62
+ readonly targetMs: number;
63
+ readonly #historyFrames: number;
64
+ readonly #frameWeight: number;
65
+ readonly #minChangeFrames: number;
66
+ readonly #panicFrames: number;
67
+ readonly #changeThreshold: number;
68
+ readonly #model: FrameTimeModel;
69
+ /** Newest last. */
70
+ #history: number[] = [];
71
+ #framesSinceChange = 0;
72
+
73
+ constructor(options: IFrameTimeBudgetOptions) {
74
+ this.periodMs = positive(options.periodMs, "periodMs");
75
+ const headroom = options.headroom ?? 0.1;
76
+ if (!(headroom >= 0 && headroom < 1))
77
+ throw new RangeError("FrameTimeBudget headroom must be in [0, 1).");
78
+ this.targetMs = this.periodMs * (1 - headroom);
79
+ this.#historyFrames = Math.floor(positive(options.historyFrames ?? 16, "historyFrames"));
80
+ this.#frameWeight = positive(options.frameWeight ?? 0.9, "frameWeight");
81
+ this.#minChangeFrames = Math.max(0, Math.floor(options.minChangeFrames ?? 8));
82
+ this.#panicFrames = Math.max(2, Math.floor(options.panicFrames ?? 2));
83
+ this.#changeThreshold = options.changeThreshold ?? 0.02;
84
+ if (!(this.#changeThreshold >= 0 && this.#changeThreshold < 1))
85
+ throw new RangeError("FrameTimeBudget changeThreshold must be in [0, 1).");
86
+ this.#model = options.model ?? "quadratic";
87
+ }
88
+
89
+ /** The caller applied a move: the old frames and the change-period count start again. */
90
+ reset(): void {
91
+ this.#history = [];
92
+ this.#framesSinceChange = 0;
93
+ }
94
+
95
+ /**
96
+ * Feeds one loop frame: the whole GPU frame in milliseconds, or `undefined` for a frame whose GPU
97
+ * time has not resolved (it counts toward the change period and enters no history).
98
+ */
99
+ observe(frameMs: number | undefined): IFrameTimeDecision {
100
+ if (frameMs !== undefined) {
101
+ if (!Number.isFinite(frameMs) || frameMs < 0)
102
+ throw new RangeError(
103
+ `FrameTimeBudget readings must be finite and at least zero, got ${frameMs}.`,
104
+ );
105
+ this.#history.push(frameMs);
106
+ if (this.#history.length > this.#historyFrames) this.#history.shift();
107
+ }
108
+ this.#framesSinceChange += 1;
109
+ const walk = this.#walk();
110
+ if (walk === undefined)
111
+ return {
112
+ direction: "hold",
113
+ frames: 0,
114
+ meanMs: undefined,
115
+ panic: false,
116
+ suggested: undefined,
117
+ };
118
+ const { consecutive, frames, meanMs, suggested } = walk;
119
+ // Unreal panics when every frame it read is over the period. A one-entry history is the first
120
+ // frame after a reset, so the run needs `panicFrames` frames to count as a run.
121
+ const panic = consecutive === frames && frames >= this.#panicFrames;
122
+ if (panic) return { direction: "down", frames, meanMs, panic, suggested };
123
+ if (this.#framesSinceChange < this.#minChangeFrames)
124
+ return { direction: "hold", frames, meanMs, panic, suggested };
125
+ const direction: FrameDirection =
126
+ suggested < 1 - this.#changeThreshold
127
+ ? "down"
128
+ : suggested > 1 + this.#changeThreshold
129
+ ? "up"
130
+ : "hold";
131
+ return { direction, frames, meanMs, panic, suggested };
132
+ }
133
+
134
+ /** Newest first, stopping at the panic run: frames before it say nothing about now. */
135
+ #walk(): { consecutive: number; frames: number; meanMs: number; suggested: number } | undefined {
136
+ let weight = 1;
137
+ let totalWeight = 0;
138
+ let sumSuggested = 0;
139
+ let sumMs = 0;
140
+ let consecutive = 0;
141
+ let frames = 0;
142
+ for (let at = this.#history.length - 1; at >= 0; at--) {
143
+ const ms = this.#history[at] as number;
144
+ consecutive = ms > this.periodMs ? consecutive + 1 : 0;
145
+ const ratio = ms === 0 ? Number.POSITIVE_INFINITY : this.targetMs / ms;
146
+ const scale = this.#model === "quadratic" ? Math.sqrt(ratio) : ratio;
147
+ sumSuggested += Math.min(scale, 1e6) * weight;
148
+ sumMs += ms * weight;
149
+ totalWeight += weight;
150
+ frames += 1;
151
+ weight *= this.#frameWeight;
152
+ if (consecutive === this.#panicFrames) break;
153
+ }
154
+ if (frames === 0) return undefined;
155
+ return {
156
+ consecutive,
157
+ frames,
158
+ meanMs: sumMs / totalWeight,
159
+ suggested: sumSuggested / totalWeight,
160
+ };
161
+ }
162
+ }
@@ -0,0 +1,231 @@
1
+ import { type IStageGpuReading, stageGpuReading } from "../render-pass-budget.js";
2
+ import { BudgetLadder, type IBudgetWindow } from "./budget-ladder.js";
3
+
4
+ /** `TN_GI` lines carry one report as JSON. */
5
+ export const GI_MARKER = "TN_GI";
6
+
7
+ /**
8
+ * The ways a game gathers bounce light, from the cheapest to the dearest. The names follow Unreal's
9
+ * `r.Lumen.FinalGatherMethod` and the three levels of `sg.GlobalIlluminationQuality` the tiers map to.
10
+ */
11
+ export const GI_METHODS = ["none", "irradianceField", "screenProbeGather"] as const;
12
+
13
+ export type GIMethod = (typeof GI_METHODS)[number];
14
+
15
+ /** `sg.GlobalIlluminationQuality` of the Unreal level each method follows (Low, Medium, Epic). */
16
+ const UNREAL_QUALITY: Readonly<Record<GIMethod, 0 | 1 | 3>> = {
17
+ irradianceField: 1,
18
+ none: 0,
19
+ screenProbeGather: 3,
20
+ };
21
+
22
+ export interface IGIBudgetReport {
23
+ /** The method the game runs. It never changes while the game runs, as in Unreal. */
24
+ readonly finalGatherMethod: GIMethod;
25
+ /** Read-only: the `sg.GlobalIlluminationQuality` the method follows. */
26
+ readonly globalIlluminationQuality: 0 | 1 | 3;
27
+ /** The quality tier the game started at, when it named one. */
28
+ readonly tier: string | undefined;
29
+ /** Mean GI-stage GPU milliseconds over the window, or `undefined` when no frame resolved. */
30
+ readonly windowMs: number | undefined;
31
+ /** Mean whole-frame GPU milliseconds over the window. */
32
+ readonly frameMs: number | undefined;
33
+ /** The GI stage's share of the GPU frame, or `undefined` when either reading is missing. */
34
+ readonly share: number | undefined;
35
+ /** The frame period the frame is compared with. */
36
+ readonly periodMs: number;
37
+ /** The frame period less its headroom. */
38
+ readonly targetMs: number;
39
+ /** Resolved whole-frame readings in the window. */
40
+ readonly samples: number;
41
+ /** 1 for the first window the watcher closes, so a reader can skip the warm-up window. */
42
+ readonly window: number;
43
+ /** Which of the named `stages` resolved in the window. Empty when a stage name is wrong: that reads as 0 ms. */
44
+ readonly stagesSeen: readonly string[];
45
+ /** Every nested pass name that resolved in the window, to find the name a stage goes by. */
46
+ readonly passes: readonly string[];
47
+ /** `over` when the frame mean is above the target. The primary resolution scale is the lever, not the method. */
48
+ readonly verdict: "over" | "within" | "unobserved";
49
+ readonly reason: string;
50
+ }
51
+
52
+ export interface IGIBudgetOptions {
53
+ /** The method the game runs: the tier's `finalGatherMethod`. */
54
+ readonly method: GIMethod;
55
+ /** Names of the render passes that are GI work (three names its passes by scene, such as `SSGI`). */
56
+ readonly stages: readonly string[];
57
+ /** The frame period in milliseconds, such as 1000 / 60. The whole GPU frame is compared with it. */
58
+ readonly framePeriodMs: number;
59
+ /** The quality tier the method came from, for the report. */
60
+ readonly tier?: string;
61
+ /** Frames per window. Default 120. */
62
+ readonly windowFrames?: number;
63
+ /** Where `TN_GI` lines go. Default `console.info`. */
64
+ readonly report?: (line: string) => void;
65
+ /** Reads a renderer's newest stage reading. Default `stageGpuReading`; a test supplies its own. */
66
+ readonly read?: (renderer: unknown) => IStageGpuReading | undefined;
67
+ }
68
+
69
+ /**
70
+ * Reports what a game's global illumination costs against the frame period. The method holds its
71
+ * scalability level while the game runs, as Unreal's Lumen does: no Lumen file declares a run-time
72
+ * budget (`sg.GlobalIlluminationQuality` comes from the benchmark or the device profile). A frame
73
+ * over its period gets cheaper through the primary resolution scale (`ResolutionScaler`), and the
74
+ * GI pass follows the lower resolution.
75
+ *
76
+ * This reads the GPU time of the passes the game names, once per resolved frame. A window of frames
77
+ * (120 by default) reports the GI share of the whole GPU frame and whether the frame fits its
78
+ * period less 10% headroom (`FrameTimeBudget`). An adapter without timestamp queries resolves no
79
+ * frame, so the window is reported unobserved.
80
+ *
81
+ * @situation global illumination costs too much on a weak GPU
82
+ * @situation see what share of the GPU frame the bounce light takes
83
+ * @situation quality tier for indirect lighting that follows the hardware
84
+ * @constraint the method never changes while the game runs: the primary resolution scale is the run-time lever
85
+ * @constraint the GPU time of a pass is read by the scene name three or the game gave it, so name every GI pass in `stages`
86
+ * @constraint timestamp queries are needed: without them every window is unobserved
87
+ * @alias lumen scalability
88
+ * @alias sg.GlobalIlluminationQuality
89
+ * @alias final gather method
90
+ * @example
91
+ * const gi = new GIBudget({ method: "screenProbeGather", stages: ["SSGI"], framePeriodMs: 1000 / 60 });
92
+ * ctx.beforeRender(() => gi.observeRenderer(ctx.renderer.raw));
93
+ */
94
+ export class GIBudget {
95
+ readonly #ladder: BudgetLadder<GIMethod>;
96
+ readonly #options: IGIBudgetOptions;
97
+ readonly #read: (renderer: unknown) => IStageGpuReading | undefined;
98
+ #lastFrame = -1;
99
+ readonly #seen = new Set<string>();
100
+ readonly #passes = new Set<string>();
101
+ #last: IGIBudgetReport | undefined;
102
+ #lastVerdict: string | undefined;
103
+
104
+ constructor(options: IGIBudgetOptions) {
105
+ if (options.stages.length === 0)
106
+ throw new RangeError("GIBudget stages must name at least one render pass.");
107
+ if (!GI_METHODS.includes(options.method))
108
+ throw new RangeError(
109
+ `GIBudget method ${String(options.method)} is not one of ${GI_METHODS.join(", ")}.`,
110
+ );
111
+ this.#options = options;
112
+ this.#read = options.read ?? stageGpuReading;
113
+ // One level: the method holds, so the ladder only measures and reports.
114
+ this.#ladder = new BudgetLadder<GIMethod>({
115
+ explicit: true,
116
+ framePeriodMs: options.framePeriodMs,
117
+ levels: [options.method],
118
+ start: options.method,
119
+ ...(options.windowFrames === undefined ? {} : { windowFrames: options.windowFrames }),
120
+ });
121
+ }
122
+
123
+ get finalGatherMethod(): GIMethod {
124
+ return this.#options.method;
125
+ }
126
+
127
+ get globalIlluminationQuality(): 0 | 1 | 3 {
128
+ return UNREAL_QUALITY[this.#options.method];
129
+ }
130
+
131
+ /** The newest closed window's report, or `undefined` before the first closes. */
132
+ lastReport(): IGIBudgetReport | undefined {
133
+ return this.#last;
134
+ }
135
+
136
+ /**
137
+ * Feeds one loop frame: the GI stages' GPU milliseconds and the whole frame's, or `undefined` for
138
+ * a frame whose GPU time has not resolved. Returns the report when this frame closes a window.
139
+ */
140
+ observe(ms: number | undefined, frameMs?: number): IGIBudgetReport | undefined {
141
+ const window = this.#ladder.observe(ms, frameMs);
142
+ if (window === undefined) return undefined;
143
+ const report = this.#toReport(window);
144
+ this.#last = report;
145
+ this.#seen.clear();
146
+ this.#passes.clear();
147
+ this.#emit(report);
148
+ return report;
149
+ }
150
+
151
+ /**
152
+ * Feeds one loop frame from a renderer the frame budget instruments: the named GI passes of the
153
+ * newest whole resolved frame, counted once however many loop frames wait for the next one.
154
+ */
155
+ observeRenderer(renderer: unknown): IGIBudgetReport | undefined {
156
+ const reading = this.#read(renderer);
157
+ if (reading === undefined || reading.frame === this.#lastFrame) return this.observe(undefined);
158
+ this.#lastFrame = reading.frame;
159
+ for (const name of Object.keys(reading.stages)) this.#passes.add(name);
160
+ let ms = 0;
161
+ for (const name of this.#options.stages) {
162
+ const stageMs = reading.stages[name];
163
+ if (stageMs === undefined) continue;
164
+ this.#seen.add(name);
165
+ ms += stageMs;
166
+ }
167
+ return this.observe(ms, reading.total);
168
+ }
169
+
170
+ #toReport(window: IBudgetWindow<GIMethod>): IGIBudgetReport {
171
+ const ms = window.windowMs;
172
+ const frame = window.frameMs;
173
+ const verdict =
174
+ window.verdict === "unobserved"
175
+ ? "unobserved"
176
+ : window.verdict === "over"
177
+ ? "over"
178
+ : "within";
179
+ const share = ms !== undefined && frame !== undefined && frame > 0 ? ms / frame : undefined;
180
+ const method = window.level;
181
+ let reason: string;
182
+ if (frame === undefined) {
183
+ reason = `no GPU time resolved in the window (${window.frames} frames): ${method} holds`;
184
+ } else if (verdict === "over") {
185
+ reason = `frame ${Number(frame.toFixed(2))} ms is over the ${Number(window.targetMs.toFixed(2))} ms target (period ${Number(window.periodMs.toFixed(2))} ms): ${method} holds, the primary resolution scale is the lever${share === undefined ? "" : `, GI is ${Math.round(share * 100)}% of the frame`}`;
186
+ } else {
187
+ reason = `frame ${Number(frame.toFixed(2))} ms is inside the ${Number(window.targetMs.toFixed(2))} ms target`;
188
+ }
189
+ return {
190
+ finalGatherMethod: method,
191
+ frameMs: frame === undefined ? undefined : Number(frame.toFixed(3)),
192
+ globalIlluminationQuality: UNREAL_QUALITY[method],
193
+ passes: [...this.#passes].sort(),
194
+ periodMs: Number(window.periodMs.toFixed(3)),
195
+ reason,
196
+ samples: window.samples,
197
+ share: share === undefined ? undefined : Number(share.toFixed(4)),
198
+ stagesSeen: [...this.#seen],
199
+ targetMs: Number(window.targetMs.toFixed(3)),
200
+ tier: this.#options.tier,
201
+ verdict,
202
+ window: window.number,
203
+ windowMs: ms === undefined ? undefined : Number(ms.toFixed(3)),
204
+ };
205
+ }
206
+
207
+ /** The first window, and a window that changes the verdict, is worth a line. */
208
+ #emit(report: IGIBudgetReport): void {
209
+ const worth = report.verdict !== this.#lastVerdict;
210
+ this.#lastVerdict = report.verdict;
211
+ if (!worth) return;
212
+ const line = `${GI_MARKER} ${JSON.stringify(report)}`;
213
+ if (this.#options.report !== undefined) this.#options.report(line);
214
+ else console.info(line);
215
+ }
216
+ }
217
+
218
+ /** Parses a `TN_GI` line back into its report, or `undefined` for any other line. */
219
+ export function readGIMarker(line: string): IGIBudgetReport | undefined {
220
+ if (!line.startsWith(`${GI_MARKER} `)) return undefined;
221
+ try {
222
+ const parsed: unknown = JSON.parse(line.slice(GI_MARKER.length + 1));
223
+ if (typeof parsed !== "object" || parsed === null) return undefined;
224
+ const report = parsed as IGIBudgetReport;
225
+ return GI_METHODS.includes(report.finalGatherMethod) && typeof report.periodMs === "number"
226
+ ? report
227
+ : undefined;
228
+ } catch {
229
+ return undefined;
230
+ }
231
+ }
@@ -0,0 +1,49 @@
1
+ import { vec4 } from "three/tsl";
2
+ import type { Node } from "three/webgpu";
3
+
4
+ /**
5
+ * What a visualize mode shows. `off` is the finished frame; `indirectDiffuse` is the bounce light alone, the
6
+ * counterpart of Unreal's `r.Lumen.Visualize.IndirectDiffuse`. Other GI work adds its modes here when its data exists.
7
+ */
8
+ export const GI_VISUALIZE_MODES = ["off", "indirectDiffuse"] as const;
9
+
10
+ export type GIVisualizeMode = (typeof GI_VISUALIZE_MODES)[number];
11
+
12
+ export interface IGIVisualizeOptions {
13
+ readonly mode: GIVisualizeMode;
14
+ /** The finished frame, returned unchanged in `off` mode. */
15
+ readonly beauty: Node<"vec4">;
16
+ /**
17
+ * The indirect diffuse light as the surface returns it: the gathered and cached light times the surface's own
18
+ * albedo, in the frame's exposure. The game's chain builds it, because it owns what the chain gathers.
19
+ */
20
+ readonly indirectDiffuse?: Node<"vec3">;
21
+ }
22
+
23
+ /**
24
+ * Shows one lighting term of a frame by itself, so a lighting difference against a reference can be told apart from a
25
+ * scene difference. The game builds each term in its own chain and picks the mode; this class only selects, and it
26
+ * fails when the chain did not build the term the mode needs, so a frame never claims to show a term it does not hold.
27
+ */
28
+ export class GIVisualize {
29
+ readonly mode: GIVisualizeMode;
30
+ /** The node to output: `beauty` for `off`, the chosen term with an opaque alpha otherwise. */
31
+ readonly node: Node<"vec4">;
32
+
33
+ constructor(options: IGIVisualizeOptions) {
34
+ if (!GI_VISUALIZE_MODES.includes(options.mode))
35
+ throw new Error(
36
+ `TN_GI_VISUALIZE_MODE: '${String(options.mode)}'. Use one of: ${GI_VISUALIZE_MODES.join(", ")}.`,
37
+ );
38
+ this.mode = options.mode;
39
+ if (options.mode === "off") {
40
+ this.node = options.beauty;
41
+ return;
42
+ }
43
+ if (options.indirectDiffuse === undefined)
44
+ throw new Error(
45
+ "TN_GI_VISUALIZE_TERM: mode 'indirectDiffuse' needs the chain's indirectDiffuse node.",
46
+ );
47
+ this.node = vec4(options.indirectDiffuse, 1);
48
+ }
49
+ }
@@ -44,6 +44,7 @@ export function materialKey(material: Material): string {
44
44
  material.type,
45
45
  material.transparent ? 1 : 0,
46
46
  num(material.alphaTest),
47
+ material.alphaHash ? 1 : 0,
47
48
  material.side,
48
49
  material.vertexColors ? 1 : 0,
49
50
  num(material.opacity),