@threenative/core 0.3.4 → 0.3.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (176) hide show
  1. package/capabilities.json +1505 -79
  2. package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
  3. package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
  4. package/dist/{game-CljaDv4D.d.ts → game-Jz4Fdoeb.d.ts} +114 -11
  5. package/dist/hot.d.ts +4 -4
  6. package/dist/index.d.ts +712 -118
  7. package/dist/index.js +12437 -4955
  8. package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
  9. package/dist/playtest.d.ts +6 -10
  10. package/dist/playtest.js +57 -24
  11. package/dist/react-css.d.ts +62 -0
  12. package/dist/react-css.js +591 -0
  13. package/dist/react.d.ts +2 -2
  14. package/dist/{renderer-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
  15. package/dist/terrain-jobs-worker.d.ts +2 -0
  16. package/dist/terrain-jobs-worker.js +130 -0
  17. package/dist/ui-layer.js +59 -8
  18. package/dist/world.d.ts +766 -73
  19. package/dist/world.js +9307 -3543
  20. package/gpl/recipes/export_world.py +18 -1
  21. package/mcp/blender-server.mjs +7 -4
  22. package/mcp/blender.mjs +3 -4
  23. package/mcp/engine-server.mjs +2 -2
  24. package/mcp/servers.mjs +4 -4
  25. package/package.json +15 -9
  26. package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
  27. package/patches/three@0.185.1.patch +6594 -700
  28. package/scripts/apply-three-patch.mjs +62 -4
  29. package/src/animation-blend.ts +264 -0
  30. package/src/animation-composition.ts +362 -0
  31. package/src/animation-layers.ts +260 -0
  32. package/src/animation-root-motion.ts +283 -0
  33. package/src/animation.ts +896 -0
  34. package/src/assets.ts +1303 -0
  35. package/src/atmosphere/index.ts +335 -0
  36. package/src/atmosphere/luts.ts +298 -0
  37. package/src/atmosphere/params.ts +323 -0
  38. package/src/audio.ts +912 -0
  39. package/src/billboard.ts +124 -0
  40. package/src/bone-lengths.ts +157 -0
  41. package/src/camera-shake.ts +116 -0
  42. package/src/canvas-layer.ts +47 -0
  43. package/src/clip-audit.ts +401 -0
  44. package/src/clustered-batch.ts +492 -0
  45. package/src/clustered-mesh.ts +638 -0
  46. package/src/compute-driven.ts +176 -0
  47. package/src/compute-timing.ts +318 -0
  48. package/src/config.ts +593 -0
  49. package/src/debug.ts +82 -0
  50. package/src/engine-render-hook.ts +25 -0
  51. package/src/entities.ts +79 -0
  52. package/src/entity-snapshot.ts +53 -0
  53. package/src/flight.ts +683 -0
  54. package/src/fluid-field.ts +748 -0
  55. package/src/fluid-particles.ts +1253 -0
  56. package/src/frame-budget.ts +1368 -0
  57. package/src/game.ts +2408 -0
  58. package/src/geometry-capture.ts +1098 -0
  59. package/src/gpu-class.ts +160 -0
  60. package/src/gpu-frame-observation.ts +424 -0
  61. package/src/gpu-readback.ts +143 -0
  62. package/src/gpu-scene-bvh.ts +464 -0
  63. package/src/grounding.ts +100 -0
  64. package/src/hot.ts +161 -0
  65. package/src/import-meta.d.ts +13 -0
  66. package/src/index.ts +1536 -0
  67. package/src/input.ts +690 -0
  68. package/src/instanced-batch-lod.ts +283 -0
  69. package/src/instanced-batch.ts +274 -0
  70. package/src/interpolation.ts +129 -0
  71. package/src/launch-diagnostics.ts +161 -0
  72. package/src/loop.ts +574 -0
  73. package/src/matrix-world.ts +245 -0
  74. package/src/merge-parts.ts +812 -0
  75. package/src/model-lod.ts +1315 -0
  76. package/src/net-protocol.ts +333 -0
  77. package/src/net-session.ts +477 -0
  78. package/src/net.ts +80 -0
  79. package/src/ocean/fft.ts +72 -0
  80. package/src/ocean/spectral.ts +728 -0
  81. package/src/particle-significance.ts +102 -0
  82. package/src/particles.ts +648 -0
  83. package/src/path-follow.ts +175 -0
  84. package/src/picking.ts +250 -0
  85. package/src/pipeline-census.ts +1566 -0
  86. package/src/platform.ts +210 -0
  87. package/src/playtest.ts +850 -0
  88. package/src/pointer-events.ts +411 -0
  89. package/src/pose-measure.ts +435 -0
  90. package/src/profiling/FrameCounters.ts +231 -0
  91. package/src/profiling/Spans.ts +548 -0
  92. package/src/profiling/opacity-convention.ts +21 -0
  93. package/src/profiling/render-list-validate.ts +175 -0
  94. package/src/profiling/render-trap-audit.ts +84 -0
  95. package/src/profiling/scene-warning.ts +190 -0
  96. package/src/profiling/span-probes.ts +191 -0
  97. package/src/profiling/unlit-foliage-warning.ts +149 -0
  98. package/src/projection-apply.ts +1529 -0
  99. package/src/projection-marker.ts +142 -0
  100. package/src/projection-plan.ts +1258 -0
  101. package/src/projection-skinned.ts +419 -0
  102. package/src/projection-stability.ts +409 -0
  103. package/src/projection-uniform.ts +328 -0
  104. package/src/random.ts +41 -0
  105. package/src/react-css.ts +604 -0
  106. package/src/react-glyphs.ts +114 -0
  107. package/src/react-host.ts +576 -0
  108. package/src/react-layout.ts +265 -0
  109. package/src/react.ts +60 -0
  110. package/src/render/alpha-antialiasing.ts +159 -0
  111. package/src/render/batched-velocity.ts +126 -0
  112. package/src/render/chain.ts +1021 -0
  113. package/src/render/daylight.ts +189 -0
  114. package/src/render/depth-pyramid.ts +596 -0
  115. package/src/render/foliage-alpha.ts +166 -0
  116. package/src/render/material-key.ts +60 -0
  117. package/src/render/mesh-pool.ts +144 -0
  118. package/src/render/probe-volume.ts +1668 -0
  119. package/src/render/resolution-subrect.ts +253 -0
  120. package/src/render/velocity.ts +442 -0
  121. package/src/render/virtual-shadow-pages.ts +827 -0
  122. package/src/render/virtual-shadow-partial.ts +174 -0
  123. package/src/render/virtual-shadow.ts +3330 -0
  124. package/src/render/world-impostor-surface.ts +722 -0
  125. package/src/render/world-impostor.ts +558 -0
  126. package/src/render-camera-cull.ts +441 -0
  127. package/src/render-pass-budget.ts +501 -0
  128. package/src/renderProjection.ts +758 -0
  129. package/src/renderer-config.ts +127 -0
  130. package/src/renderer.ts +1847 -0
  131. package/src/replay-protocol.ts +85 -0
  132. package/src/replay.ts +205 -0
  133. package/src/resolution-scaler.ts +819 -0
  134. package/src/rig-preparation.ts +271 -0
  135. package/src/ripple-field.ts +432 -0
  136. package/src/scale.ts +109 -0
  137. package/src/scene.ts +239 -0
  138. package/src/schedule.ts +155 -0
  139. package/src/skeletal-mesh.ts +61 -0
  140. package/src/skeleton.ts +100 -0
  141. package/src/snow-field.ts +744 -0
  142. package/src/softbody-topology.ts +269 -0
  143. package/src/softbody.ts +516 -0
  144. package/src/sprite-animator.ts +222 -0
  145. package/src/startup-readiness.ts +386 -0
  146. package/src/state.ts +66 -0
  147. package/src/static-transform.ts +274 -0
  148. package/src/storage-buffer.ts +253 -0
  149. package/src/streaming.ts +308 -0
  150. package/src/target-fps.ts +92 -0
  151. package/src/terrain-jobs-worker.ts +17 -0
  152. package/src/terrain-jobs.ts +353 -0
  153. package/src/textures.ts +39 -0
  154. package/src/tracers.ts +237 -0
  155. package/src/ui-bridge.ts +368 -0
  156. package/src/ui-hit-regions.ts +380 -0
  157. package/src/ui-layer.ts +83 -0
  158. package/src/ui-state.ts +220 -0
  159. package/src/version.ts +2 -0
  160. package/src/viewport.ts +253 -0
  161. package/src/warmup.ts +1357 -0
  162. package/src/water-surface.ts +384 -0
  163. package/src/wave-field.ts +524 -0
  164. package/src/world-capabilities.ts +131 -0
  165. package/src/world-cell-proxy.ts +392 -0
  166. package/src/world-cells.ts +10564 -0
  167. package/src/world-gpu-scene.ts +3354 -0
  168. package/src/world-heightmap.ts +82 -0
  169. package/src/world-package.ts +469 -0
  170. package/src/world-passes.ts +582 -0
  171. package/src/world-region.ts +17 -0
  172. package/src/world-terrain-splat.ts +564 -0
  173. package/src/world-tiles.ts +3826 -0
  174. package/src/world-topology.ts +370 -0
  175. package/src/world-validate.ts +48 -0
  176. package/src/world.ts +805 -0
@@ -0,0 +1,501 @@
1
+ /**
2
+ * Per-pass draw and triangle attribution, on by default, for every platform.
3
+ *
4
+ * The frame budget already owned the milliseconds; this owns the submissions. Three's
5
+ * `renderer.info.reset()` runs once per frame before the world render, and a nested shadow or
6
+ * reflection `renderer.render(...)` shares that same `info`, so `info.render` reports main plus
7
+ * every nested pass combined. The aggregate cannot tell a 316-draw shadow lane from a 1,418-draw
8
+ * colour pass, and every optimisation attempt had to hand-roll the split. This is the split: each
9
+ * `render()` is one entry on a stack, and its own submissions are the counter delta across its
10
+ * call minus the deltas of the nested calls it made, so the innermost active render call owns
11
+ * exactly what it submitted.
12
+ *
13
+ * Three names its own shadow pass by temporarily renaming the scene to `Shadow Map [ ... ]`
14
+ * (`renderShadow`), and a reflection pass names its scene with `Reflector` in it. Those are
15
+ * borrowed, not invented: the classifier reads three's vocabulary and falls back to `nested`.
16
+ *
17
+ * Measurement, not policy: installing this alters no draw. `install` answers `undefined` on a
18
+ * renderer whose `info.render` cannot be read, and a consumer must then report the pass split as
19
+ * absent rather than zero.
20
+ *
21
+ * The main pass's own draws are also split by where their mesh came from, counted at the one place
22
+ * a draw is counted — `info.update`, which every backend calls per submitted draw with the object
23
+ * that owns it — so the sources sum to `draws` by construction instead of by an estimate beside it.
24
+ */
25
+
26
+ /** The named kinds of a render pass. Closed on purpose: a consumer bounds a known kind. */
27
+ export const FRAME_PASS_KINDS = ["main", "shadow", "reflection", "nested"] as const;
28
+
29
+ export type FramePassKind = (typeof FRAME_PASS_KINDS)[number];
30
+
31
+ /**
32
+ * Where a main-pass draw's mesh came from. Closed, and `other` is the default.
33
+ *
34
+ * Each entry is a system that owns its meshes and writes the origin on them, so the split reads as
35
+ * an answer about systems rather than about geometry: `gpuScene` and `bundles` are `WorldCells`' two
36
+ * ways of drawing one main batch (a GPU-dressed key, and the same mesh replayed from the world's
37
+ * bundle), `terrain` is every mesh `world-tiles.ts` creates, `proxies` is the shadow halves and the
38
+ * whole-map impostor aggregates, `chunks` is a hand-placed chunk's own draws, `instanced` is a main
39
+ * batch the GPU scene never dressed, and `sky` is a daylight rig's sky box. What is left in `other`
40
+ * is a mesh no world system claimed — a character, a prop, a water surface the game loaded — which is
41
+ * the bucket that has to be small enough to be worth naming one draw at a time.
42
+ */
43
+ export const MAIN_DRAW_SOURCES = [
44
+ "gpuScene",
45
+ "bundles",
46
+ "terrain",
47
+ "proxies",
48
+ "chunks",
49
+ "instanced",
50
+ "sky",
51
+ "other",
52
+ ] as const;
53
+
54
+ export type MainDrawSource = (typeof MAIN_DRAW_SOURCES)[number];
55
+
56
+ /**
57
+ * One render call's own submissions, attributed to its innermost active render call.
58
+ *
59
+ * `drawsBySource` is `main`'s own draws by origin, in the frame's counts rather than in percentiles:
60
+ * it sums to `draws` for the frame, which is the claim the split exists to answer. Absent when the
61
+ * renderer named no object for one of those draws, because a split that guessed where a draw came
62
+ * from would read as a measurement.
63
+ */
64
+ export interface IRenderPassSample {
65
+ readonly draws: number;
66
+ readonly drawsBySource?: Readonly<Partial<Record<MainDrawSource, number>>>;
67
+ readonly kind: FramePassKind;
68
+ readonly triangles: number;
69
+ }
70
+
71
+ /** Whether a tag names a source this file counts. Anything else is `other`. */
72
+ function isMainDrawSource(tag: unknown): tag is MainDrawSource {
73
+ return (MAIN_DRAW_SOURCES as readonly unknown[]).includes(tag);
74
+ }
75
+
76
+ /**
77
+ * The source a drawn object belongs to, read from the two tags its creator set on it.
78
+ *
79
+ * `tnBundled` is the marker `WorldCells` already keeps, and it wins: a bundled mesh is a mesh the
80
+ * world drew through a recorded `BundleGroup` rather than one it submitted per object, so counting
81
+ * it as a GPU-scene key as well would name the same draw twice.
82
+ */
83
+ function drawSourceOf(object: unknown): MainDrawSource | undefined {
84
+ const userData =
85
+ typeof object === "object" && object !== null
86
+ ? (object as { readonly userData?: Record<string, unknown> }).userData
87
+ : undefined;
88
+ if (typeof userData !== "object" || userData === null) return undefined;
89
+ if (userData.tnBundled === true) return "bundles";
90
+ const tagged = userData.tnDrawSource;
91
+ return isMainDrawSource(tagged) ? tagged : "other";
92
+ }
93
+
94
+ interface IRenderCounters {
95
+ readonly drawCalls?: number;
96
+ readonly calls?: number;
97
+ readonly triangles?: number;
98
+ }
99
+
100
+ /**
101
+ * Three's own per-frame counters, the surface this file reads and wraps.
102
+ *
103
+ * `update` is three's per-draw counter, not one of the aggregates: WebGPU's `WebGPUInfo` and the
104
+ * WebGL2 fallback inside it both call it once per submitted draw with the object that owns it, and
105
+ * a standalone `WebGLRenderer` calls it with a vertex count instead — which is why a draw this
106
+ * cannot read a `userData` off is left unattributed rather than guessed at.
107
+ */
108
+ interface IInfoCounters {
109
+ readonly render?: IRenderCounters | undefined;
110
+ update?(object: unknown, count: number, instanceCount: number): void;
111
+ }
112
+
113
+ /**
114
+ * The slice of three's timestamp query pool this reads.
115
+ *
116
+ * Three keys one pool per query type (`render`, `compute`) at
117
+ * `renderer.backend.timestampQueryPool`, and each pool exposes the two maps it fills in itself:
118
+ * `queryOffsets` is the uid of every allocated pass (appended synchronously as the pass begins,
119
+ * cleared when a resolve starts) and `timestamps` is every uid's resolved duration in
120
+ * milliseconds, written when the asynchronous resolve lands. Both are three's own public fields,
121
+ * not a borrowed internal, and reading them is what turns the one summed `info.render.timestamp`
122
+ * into a per-pass number.
123
+ */
124
+ export interface ITimestampQueryPool {
125
+ readonly queryOffsets?: Map<string, number> | undefined;
126
+ readonly timestamps?: Map<string, number> | undefined;
127
+ }
128
+
129
+ /**
130
+ * The slice of a renderer this reads: the raw three renderer, not `IRendererLike`. It is
131
+ * deliberately structural so the unit test can stand in a fake that nests exactly as three does.
132
+ */
133
+ export interface IRenderPassTarget {
134
+ readonly info?: IInfoCounters | undefined;
135
+ /**
136
+ * Three's backend, for per-pass GPU time. Optional: a WebGL2 fallback and a test double may
137
+ * carry no timestamp pool, and every GPU read is then absent rather than zero.
138
+ */
139
+ readonly backend?:
140
+ | { readonly timestampQueryPool?: Record<string, ITimestampQueryPool | null> }
141
+ | undefined;
142
+ render(scene: unknown, camera: unknown): void;
143
+ }
144
+
145
+ /** One allocated timestamp query, before its duration resolves: the pass kind and three's uid. */
146
+ interface IGpuUidEntry {
147
+ readonly kind: FramePassKind;
148
+ readonly uid: string;
149
+ }
150
+
151
+ /**
152
+ * One resolved frame's GPU milliseconds: the frame it belongs to, its own passes, and every pass it
153
+ * drew. `total` is the frame's cost — three's `framesDuration` for that frame, read back from the
154
+ * per-pass map rather than from the single number its resolve returns.
155
+ *
156
+ * A reading exists only when **every** pass the frame recorded has a resolved timestamp. A frame
157
+ * with any pass still in flight understates the frame's cost if its resolved parts were summed and
158
+ * forwarded as the whole, so it stays absent until the read is complete. Frames are delivered in
159
+ * order and an unresolved one is skipped, never waited on: once a newer frame is delivered the
160
+ * older unresolved frame is intentionally omitted — a missing reading, never a partial zero.
161
+ */
162
+ export interface IGpuFrameReading {
163
+ readonly frame: number;
164
+ /** Milliseconds the main pass cost. `0` when the frame drew none; whole whenever the frame is. */
165
+ readonly main: number;
166
+ /**
167
+ * Every shadow pass's milliseconds: `0` when the frame drew none. A resolved `0` is a real
168
+ * render that cost nothing, so {@link shadowPasses} — not this value — says whether one was made.
169
+ */
170
+ readonly shadow: number;
171
+ /**
172
+ * How many shadow passes the frame recorded. `0` means it drew no shadow; `> 0` means it rendered
173
+ * one, however small the cost. This is the producer's own record, so a consumer never has to guess
174
+ * "rendered" from a value that a genuine render can leave at zero.
175
+ */
176
+ readonly shadowPasses: number;
177
+ /** Every resolved pass of the frame — main, shadow and everything else. Whole, never partial. */
178
+ readonly total: number;
179
+ }
180
+
181
+ interface IPassFrame {
182
+ readonly entryDraws: number;
183
+ readonly entryTriangles: number;
184
+ readonly kind: FramePassKind;
185
+ childDraws: number;
186
+ childTriangles: number;
187
+ /** Timestamp uids the nested calls this pass made allocated, in allocation order. */
188
+ childUids?: string[];
189
+ /** This pass's own draws per origin, held only for a main pass and dropped the moment one is unclassifiable. */
190
+ drawsBySource?: Partial<Record<MainDrawSource, number>>;
191
+ /** A draw named no object to read, so {@link drawsBySource} would be a partial answer. */
192
+ unclassifiable?: boolean;
193
+ }
194
+
195
+ function readCounters(target: IRenderPassTarget): { draws: number; triangles: number } | undefined {
196
+ const render = target.info?.render;
197
+ if (render === undefined) return undefined;
198
+ const draws = render.drawCalls ?? render.calls;
199
+ const triangles = render.triangles;
200
+ if (typeof draws !== "number" || !Number.isFinite(draws) || draws < 0) return undefined;
201
+ if (typeof triangles !== "number" || !Number.isFinite(triangles) || triangles < 0)
202
+ return undefined;
203
+ return { draws, triangles };
204
+ }
205
+
206
+ const installed = new WeakSet<object>();
207
+
208
+ /**
209
+ * Resolved frames kept for GPU attribution. A resolve lags the frame it measures by a few frames,
210
+ * so the uid list for a frame must outlive the frame that produced it; 64 frames is far more than
211
+ * that lag and bounds the map on a game that never resolves.
212
+ */
213
+ const GPU_UID_FRAME_LIMIT = 64;
214
+
215
+ /**
216
+ * Names a render call by what three already calls it: the outermost call is the main camera, and a
217
+ * nested call carries the scene name three or the reflector gave it.
218
+ */
219
+ function passKind(scene: unknown, depth: number): FramePassKind {
220
+ if (depth === 0) return "main";
221
+ const name =
222
+ typeof scene === "object" &&
223
+ scene !== null &&
224
+ typeof (scene as { name?: unknown }).name === "string"
225
+ ? (scene as { name: string }).name
226
+ : "";
227
+ if (name.startsWith("Shadow Map")) return "shadow";
228
+ if (/reflect/iu.test(name)) return "reflection";
229
+ return "nested";
230
+ }
231
+
232
+ /**
233
+ * Records one presented frame's passes. The owner calls `beginFrame` before the world render and
234
+ * `passes()` after it; a nested render inside the world render is attributed without the owner
235
+ * knowing it happened.
236
+ */
237
+ /** The last resolved shadow-pass GPU milliseconds per instrumented renderer; see {@link shadowRedrawGpuMs}. */
238
+ const lastShadowGpuMs = new WeakMap<object, number>();
239
+
240
+ /**
241
+ * What the last resolved frame that drew a shadow spent on its shadow passes, on this renderer, or
242
+ * `undefined` before one resolved (or with no recorder installed). A shadow node reads it to price
243
+ * a redraw in GPU time: its own `performance.now()` around the draw is only the CPU encode.
244
+ */
245
+ export function shadowRedrawGpuMs(renderer: unknown): number | undefined {
246
+ return typeof renderer === "object" && renderer !== null
247
+ ? lastShadowGpuMs.get(renderer)
248
+ : undefined;
249
+ }
250
+
251
+ /** Records a resolved shadow-pass reading for {@link shadowRedrawGpuMs}; the recorder's own feed. */
252
+ export function noteShadowRedrawGpuMs(renderer: object, ms: number): void {
253
+ lastShadowGpuMs.set(renderer, ms);
254
+ }
255
+
256
+ export class RenderPassBudget {
257
+ readonly #target: IRenderPassTarget;
258
+ readonly #original: (scene: unknown, camera: unknown) => void;
259
+ readonly #frame: IRenderPassSample[] = [];
260
+ readonly #stack: IPassFrame[] = [];
261
+ /** Timestamp uids each render call allocated, keyed by the Three.js frame they belong to. */
262
+ readonly #gpuUids = new Map<number, IGpuUidEntry[]>();
263
+ /** The last frame `nextGpuFrame` handed out; every earlier frame has been reported. */
264
+ #deliveredGpuFrame = -1;
265
+
266
+ private constructor(target: IRenderPassTarget) {
267
+ this.#target = target;
268
+ this.#original = target.render;
269
+ const instrumented = (scene: unknown, camera: unknown): void => {
270
+ const counters = readCounters(target);
271
+ if (counters === undefined) {
272
+ this.#original.call(target, scene, camera);
273
+ return;
274
+ }
275
+ const offsets = target.backend?.timestampQueryPool?.render?.queryOffsets;
276
+ const allocatedBefore = offsets?.size ?? 0;
277
+ const depth = this.#stack.length;
278
+ const frame: IPassFrame = {
279
+ childDraws: 0,
280
+ childTriangles: 0,
281
+ entryDraws: counters.draws,
282
+ entryTriangles: counters.triangles,
283
+ kind: passKind(scene, depth),
284
+ };
285
+ this.#stack.push(frame);
286
+ try {
287
+ this.#original.call(target, scene, camera);
288
+ } finally {
289
+ this.#stack.pop();
290
+ const after = readCounters(target);
291
+ if (after !== undefined) {
292
+ const totalDraws = after.draws - frame.entryDraws;
293
+ const totalTriangles = after.triangles - frame.entryTriangles;
294
+ const parent = this.#stack[this.#stack.length - 1];
295
+ if (parent !== undefined) {
296
+ parent.childDraws += totalDraws;
297
+ parent.childTriangles += totalTriangles;
298
+ }
299
+ const drawsBySource = frame.unclassifiable === true ? undefined : frame.drawsBySource;
300
+ this.#frame.push({
301
+ draws: Math.max(0, totalDraws - frame.childDraws),
302
+ ...(drawsBySource === undefined ? {} : { drawsBySource }),
303
+ kind: frame.kind,
304
+ triangles: Math.max(0, totalTriangles - frame.childTriangles),
305
+ });
306
+ }
307
+ this.#attributeGpu(frame, offsets, allocatedBefore);
308
+ }
309
+ };
310
+ target.render = instrumented;
311
+ this.#instrumentDraws(target.info);
312
+ installed.add(target);
313
+ }
314
+
315
+ /**
316
+ * Attributes each counted draw to the origin of the object behind it.
317
+ *
318
+ * Only a draw the main pass itself submitted is counted, because a nested render's draws are
319
+ * subtracted out of `main`: counting them here too would put shadow work in the main pass's split
320
+ * and break the sum the split exists to reconcile. The original `update` still runs, so
321
+ * `info.render.drawCalls` — the number everything else is read against — is untouched.
322
+ */
323
+ #instrumentDraws(info: IInfoCounters | undefined): void {
324
+ const update = info?.update;
325
+ if (info === undefined || typeof update !== "function") return;
326
+ info.update = (object: unknown, count: number, instanceCount: number): void => {
327
+ const frame = this.#stack[this.#stack.length - 1];
328
+ if (frame?.kind === "main" && frame.unclassifiable !== true) {
329
+ const source = drawSourceOf(object);
330
+ if (source === undefined) frame.unclassifiable = true;
331
+ else {
332
+ frame.drawsBySource ??= {};
333
+ const drawsBySource = frame.drawsBySource;
334
+ drawsBySource[source] = (drawsBySource[source] ?? 0) + 1;
335
+ }
336
+ }
337
+ update.call(info, object, count, instanceCount);
338
+ };
339
+ }
340
+
341
+ /**
342
+ * Instruments `target`'s `render` in place and answers the recorder, or `undefined` when the
343
+ * renderer cannot report its own counters. Refuses a double install: one frame must not be
344
+ * counted twice.
345
+ */
346
+ static install(target: IRenderPassTarget): RenderPassBudget | undefined {
347
+ if (installed.has(target)) return undefined;
348
+ if (readCounters(target) === undefined) return undefined;
349
+ return new RenderPassBudget(target);
350
+ }
351
+
352
+ /**
353
+ * The kind of the innermost render call currently running, or undefined outside one.
354
+ *
355
+ * A per-object diagnostic needs the same attribution this class already does: a mesh submitted
356
+ * inside a shadow render is shadow work, and charging it to the main pass is how a shadow map
357
+ * disappears from a cost report.
358
+ */
359
+ activeKind(): FramePassKind | undefined {
360
+ return this.#stack[this.#stack.length - 1]?.kind;
361
+ }
362
+
363
+ /** Clears the previous frame's passes. Call before the frame's first world render. */
364
+ beginFrame(): void {
365
+ this.#frame.length = 0;
366
+ }
367
+
368
+ /**
369
+ * The passes just recorded, children before the main call. The array is reused, so a consumer
370
+ * reads it before the next `beginFrame`.
371
+ */
372
+ passes(): readonly IRenderPassSample[] {
373
+ return this.#frame;
374
+ }
375
+
376
+ /**
377
+ * The oldest resolved frame that has not been handed out yet, and where its GPU time went.
378
+ *
379
+ * Three answers a resolve with **one** number: the summed duration of the last frame in the
380
+ * batch (`three.webgpu.js:83746`). Every other frame that batch measured is written to the pool's
381
+ * own `timestamps` map, one entry per pass, keyed by the frame its uid names, and read by nobody.
382
+ * A resolve that caught up on k sampled frames therefore reported one of them, and the k-1 others
383
+ * were gone for good, because the pool is emptied before the resolve is submitted and the next one
384
+ * starts from nothing.
385
+ *
386
+ * That is what made the frame budget's sample count a function of frame *rate*: the engine asked
387
+ * for a resolve on the same 1-in-8 stride it samples on, three skips a resolve while one is still
388
+ * in flight, and the stride is a frame count where the round trip is not — so the faster the game
389
+ * presented, the fewer samples a window carried (28 in a 300-frame window on the 2026-10-03
390
+ * Machinefall probe, 1-2 in its ~200 fps windows, against the ~37 the sampler asked for).
391
+ *
392
+ * The uid list per frame is already kept here, so the batch is walked instead of collapsed: one
393
+ * sample per presented frame, one frame per sample, which is the shape the budget's series wants.
394
+ * Frames are delivered in uid order and an unresolved one is skipped rather than waited on, so no
395
+ * one frame ever stalls the frames behind it. An unresolved frame is retried only while it is the
396
+ * oldest undelivered one: the moment a newer complete frame is delivered, the cursor moves past
397
+ * the gap and the older unresolved frame is intentionally omitted — a missing reading, never a
398
+ * zeroed partial. Only the bounded uid ring retires a frame that never resolves at all.
399
+ *
400
+ * A kind with no pass in the frame is zero, not absent: a frame that drew a main pass and no
401
+ * shadow genuinely spent 0 ms on shadow. A frame is absent, though, until **every** pass it
402
+ * recorded has resolved: its parts are only a whole frame when the whole frame came back, and a
403
+ * partial `total` forwarded as the frame's cost is what the phase comparison must not read.
404
+ * The caller subtracts the known kinds from `total` to leave `other` (post chain, reflection,
405
+ * HUD). Passes are summed per kind, so a shadow cascade's several passes are one number, and main
406
+ * never absorbs the nested shadow's.
407
+ */
408
+ nextGpuFrame(): IGpuFrameReading | undefined {
409
+ for (const frame of this.#gpuUids.keys()) {
410
+ if (frame <= this.#deliveredGpuFrame) continue;
411
+ const sum = this.#gpuSum(frame);
412
+ if (sum === undefined) continue;
413
+ this.#deliveredGpuFrame = frame;
414
+ if (sum.shadowPasses > 0) noteShadowRedrawGpuMs(this.#target, sum.shadow);
415
+ return {
416
+ frame,
417
+ main: sum.main,
418
+ shadow: sum.shadow,
419
+ shadowPasses: sum.shadowPasses,
420
+ total: sum.total,
421
+ };
422
+ }
423
+ return undefined;
424
+ }
425
+
426
+ /**
427
+ * One frame's resolved GPU milliseconds from the pool's per-pass map, or `undefined` until every
428
+ * pass it recorded has come back. `total` is every resolved pass of the frame — main, shadow and
429
+ * everything else — so the frame's own cost does not have to be inferred from three's one number
430
+ * for the batch, and it is only ever returned whole.
431
+ */
432
+ #gpuSum(
433
+ frame: number,
434
+ ): { main: number; shadow: number; shadowPasses: number; total: number } | undefined {
435
+ const entries = this.#gpuUids.get(frame);
436
+ const timestamps = this.#target.backend?.timestampQueryPool?.render?.timestamps;
437
+ if (timestamps === undefined || entries === undefined || entries.length === 0) return undefined;
438
+ let main = 0;
439
+ let shadow = 0;
440
+ let shadowPasses = 0;
441
+ let total = 0;
442
+ let resolved = 0;
443
+ for (const { kind, uid } of entries) {
444
+ if (kind === "shadow") shadowPasses += 1;
445
+ const ms = timestamps.get(uid);
446
+ if (ms === undefined || !Number.isFinite(ms) || ms < 0) continue;
447
+ resolved += 1;
448
+ total += ms;
449
+ if (kind === "main") main += ms;
450
+ else if (kind === "shadow") shadow += ms;
451
+ }
452
+ // A partial sum is not the frame's cost: subtracting the known kinds from a partial `total`
453
+ // leaves an `other` no one measured. The frame stays absent until the whole read is in.
454
+ if (resolved !== entries.length) return undefined;
455
+ return { main, shadow, shadowPasses, total };
456
+ }
457
+
458
+ /**
459
+ * Attributes the uids allocated during one render call to that call, not its parent, by the same
460
+ * child-subtraction the draws get: a nested render's uids are claimed by the nested frame before
461
+ * the parent computes its own, so `main` does not absorb a shadow's pass.
462
+ */
463
+ #attributeGpu(
464
+ frame: IPassFrame,
465
+ offsets: Map<string, number> | undefined,
466
+ allocatedBefore: number,
467
+ ): void {
468
+ if (offsets === undefined || offsets.size <= allocatedBefore) return;
469
+ const allocated: string[] = [];
470
+ let index = 0;
471
+ for (const uid of offsets.keys()) {
472
+ index += 1;
473
+ if (index > allocatedBefore) allocated.push(uid);
474
+ }
475
+ if (allocated.length === 0) return;
476
+ const childUids = frame.childUids;
477
+ const own =
478
+ childUids === undefined ? allocated : allocated.filter((uid) => !childUids.includes(uid));
479
+ const parent = this.#stack[this.#stack.length - 1];
480
+ if (parent !== undefined) {
481
+ parent.childUids ??= [];
482
+ parent.childUids.push(...allocated);
483
+ }
484
+ for (const uid of own) this.#recordGpuUid(uid, frame.kind);
485
+ }
486
+
487
+ /** Files one allocated uid under the frame the uid names, dropping the oldest frames over time. */
488
+ #recordGpuUid(uid: string, kind: FramePassKind): void {
489
+ const match = /:f(\d+)$/u.exec(uid);
490
+ if (match === null) return;
491
+ const frame = Number(match[1]);
492
+ const entries = this.#gpuUids.get(frame);
493
+ if (entries === undefined) this.#gpuUids.set(frame, [{ kind, uid }]);
494
+ else entries.push({ kind, uid });
495
+ while (this.#gpuUids.size > GPU_UID_FRAME_LIMIT) {
496
+ const oldest = this.#gpuUids.keys().next().value;
497
+ if (oldest === undefined) break;
498
+ this.#gpuUids.delete(oldest);
499
+ }
500
+ }
501
+ }