@threenative/core 0.3.3 → 0.3.5

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 (182) hide show
  1. package/capabilities.json +2019 -59
  2. package/dist/{assets-CYKk2WTu.d.ts → assets-CqvE429w.d.ts} +45 -3
  3. package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
  4. package/dist/{canvas-layer-C1SnMoJ-.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
  5. package/dist/{game-D_6r-k4Y.d.ts → game-Bj8G1wmD.d.ts} +242 -17
  6. package/dist/hot.d.ts +5 -5
  7. package/dist/index.d.ts +1131 -105
  8. package/dist/index.js +15201 -4782
  9. package/dist/model-lod-BDAUYgsS.d.ts +197 -0
  10. package/dist/playtest.d.ts +6 -4
  11. package/dist/playtest.js +84 -11
  12. package/dist/react-css.d.ts +62 -0
  13. package/dist/react-css.js +591 -0
  14. package/dist/react.d.ts +2 -2
  15. package/dist/{renderer-Cy4qeBOA.d.ts → renderer-9yEo9hPa.d.ts} +676 -21
  16. package/dist/terrain-jobs-worker.d.ts +2 -0
  17. package/dist/terrain-jobs-worker.js +130 -0
  18. package/dist/ui-layer.d.ts +5 -3
  19. package/dist/ui-layer.js +59 -8
  20. package/dist/world.d.ts +1596 -17
  21. package/dist/world.js +17035 -521
  22. package/gpl/fixtures/make_world_fixture.py +184 -0
  23. package/gpl/recipes/_common.py +11 -0
  24. package/gpl/recipes/decimate.py +11 -5
  25. package/gpl/recipes/export_world.py +699 -0
  26. package/mcp/blender-server.mjs +61 -4
  27. package/mcp/blender.mjs +3 -4
  28. package/mcp/engine-server.mjs +55 -21
  29. package/mcp/servers.mjs +4 -4
  30. package/package.json +15 -9
  31. package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
  32. package/patches/three@0.185.1.patch +8246 -389
  33. package/scripts/apply-three-patch.mjs +123 -41
  34. package/src/animation-blend.ts +264 -0
  35. package/src/animation-composition.ts +362 -0
  36. package/src/animation-layers.ts +260 -0
  37. package/src/animation-root-motion.ts +283 -0
  38. package/src/animation.ts +896 -0
  39. package/src/assets.ts +1303 -0
  40. package/src/atmosphere/index.ts +335 -0
  41. package/src/atmosphere/luts.ts +298 -0
  42. package/src/atmosphere/params.ts +323 -0
  43. package/src/audio.ts +912 -0
  44. package/src/billboard.ts +124 -0
  45. package/src/bone-lengths.ts +157 -0
  46. package/src/camera-shake.ts +116 -0
  47. package/src/canvas-layer.ts +47 -0
  48. package/src/clip-audit.ts +401 -0
  49. package/src/clustered-batch.ts +492 -0
  50. package/src/clustered-mesh.ts +638 -0
  51. package/src/compute-driven.ts +176 -0
  52. package/src/compute-timing.ts +318 -0
  53. package/src/config.ts +593 -0
  54. package/src/debug.ts +82 -0
  55. package/src/engine-render-hook.ts +25 -0
  56. package/src/entities.ts +79 -0
  57. package/src/entity-snapshot.ts +53 -0
  58. package/src/flight.ts +683 -0
  59. package/src/fluid-field.ts +748 -0
  60. package/src/fluid-particles.ts +1253 -0
  61. package/src/frame-budget.ts +1368 -0
  62. package/src/game.ts +2390 -0
  63. package/src/geometry-capture.ts +1098 -0
  64. package/src/gpu-class.ts +160 -0
  65. package/src/gpu-frame-observation.ts +424 -0
  66. package/src/gpu-readback.ts +143 -0
  67. package/src/gpu-scene-bvh.ts +464 -0
  68. package/src/grounding.ts +100 -0
  69. package/src/hot.ts +161 -0
  70. package/src/import-meta.d.ts +13 -0
  71. package/src/index.ts +1536 -0
  72. package/src/input.ts +690 -0
  73. package/src/instanced-batch-lod.ts +283 -0
  74. package/src/instanced-batch.ts +274 -0
  75. package/src/interpolation.ts +129 -0
  76. package/src/launch-diagnostics.ts +161 -0
  77. package/src/loop.ts +564 -0
  78. package/src/matrix-world.ts +245 -0
  79. package/src/merge-parts.ts +812 -0
  80. package/src/model-lod.ts +1315 -0
  81. package/src/net-protocol.ts +333 -0
  82. package/src/net-session.ts +477 -0
  83. package/src/net.ts +80 -0
  84. package/src/ocean/fft.ts +72 -0
  85. package/src/ocean/spectral.ts +728 -0
  86. package/src/particle-significance.ts +102 -0
  87. package/src/particles.ts +648 -0
  88. package/src/path-follow.ts +175 -0
  89. package/src/picking.ts +250 -0
  90. package/src/pipeline-census.ts +1566 -0
  91. package/src/platform.ts +210 -0
  92. package/src/playtest.ts +839 -0
  93. package/src/pointer-events.ts +411 -0
  94. package/src/pose-measure.ts +435 -0
  95. package/src/profiling/FrameCounters.ts +231 -0
  96. package/src/profiling/Spans.ts +548 -0
  97. package/src/profiling/opacity-convention.ts +21 -0
  98. package/src/profiling/render-list-validate.ts +175 -0
  99. package/src/profiling/render-trap-audit.ts +84 -0
  100. package/src/profiling/scene-warning.ts +190 -0
  101. package/src/profiling/span-probes.ts +191 -0
  102. package/src/profiling/unlit-foliage-warning.ts +149 -0
  103. package/src/projection-apply.ts +1529 -0
  104. package/src/projection-marker.ts +142 -0
  105. package/src/projection-plan.ts +1258 -0
  106. package/src/projection-skinned.ts +419 -0
  107. package/src/projection-stability.ts +409 -0
  108. package/src/projection-uniform.ts +328 -0
  109. package/src/random.ts +41 -0
  110. package/src/react-css.ts +604 -0
  111. package/src/react-glyphs.ts +114 -0
  112. package/src/react-host.ts +576 -0
  113. package/src/react-layout.ts +265 -0
  114. package/src/react.ts +60 -0
  115. package/src/render/alpha-antialiasing.ts +159 -0
  116. package/src/render/batched-velocity.ts +126 -0
  117. package/src/render/chain.ts +1021 -0
  118. package/src/render/daylight.ts +189 -0
  119. package/src/render/depth-pyramid.ts +596 -0
  120. package/src/render/foliage-alpha.ts +166 -0
  121. package/src/render/material-key.ts +60 -0
  122. package/src/render/mesh-pool.ts +144 -0
  123. package/src/render/probe-volume.ts +1668 -0
  124. package/src/render/resolution-subrect.ts +253 -0
  125. package/src/render/velocity.ts +442 -0
  126. package/src/render/virtual-shadow-pages.ts +827 -0
  127. package/src/render/virtual-shadow-partial.ts +174 -0
  128. package/src/render/virtual-shadow.ts +3330 -0
  129. package/src/render/world-impostor-surface.ts +722 -0
  130. package/src/render/world-impostor.ts +558 -0
  131. package/src/render-camera-cull.ts +441 -0
  132. package/src/render-pass-budget.ts +501 -0
  133. package/src/renderProjection.ts +758 -0
  134. package/src/renderer-config.ts +127 -0
  135. package/src/renderer.ts +1847 -0
  136. package/src/replay-protocol.ts +85 -0
  137. package/src/replay.ts +205 -0
  138. package/src/resolution-scaler.ts +819 -0
  139. package/src/rig-preparation.ts +271 -0
  140. package/src/ripple-field.ts +432 -0
  141. package/src/scale.ts +109 -0
  142. package/src/scene.ts +239 -0
  143. package/src/schedule.ts +155 -0
  144. package/src/skeletal-mesh.ts +61 -0
  145. package/src/skeleton.ts +100 -0
  146. package/src/snow-field.ts +744 -0
  147. package/src/softbody-topology.ts +269 -0
  148. package/src/softbody.ts +516 -0
  149. package/src/sprite-animator.ts +222 -0
  150. package/src/startup-readiness.ts +386 -0
  151. package/src/state.ts +66 -0
  152. package/src/static-transform.ts +274 -0
  153. package/src/storage-buffer.ts +253 -0
  154. package/src/streaming.ts +308 -0
  155. package/src/target-fps.ts +92 -0
  156. package/src/terrain-jobs-worker.ts +17 -0
  157. package/src/terrain-jobs.ts +353 -0
  158. package/src/textures.ts +39 -0
  159. package/src/tracers.ts +237 -0
  160. package/src/ui-bridge.ts +368 -0
  161. package/src/ui-hit-regions.ts +380 -0
  162. package/src/ui-layer.ts +83 -0
  163. package/src/ui-state.ts +220 -0
  164. package/src/version.ts +2 -0
  165. package/src/viewport.ts +253 -0
  166. package/src/warmup.ts +1357 -0
  167. package/src/water-surface.ts +384 -0
  168. package/src/wave-field.ts +524 -0
  169. package/src/world-capabilities.ts +131 -0
  170. package/src/world-cell-proxy.ts +392 -0
  171. package/src/world-cells.ts +10564 -0
  172. package/src/world-gpu-scene.ts +3354 -0
  173. package/src/world-heightmap.ts +82 -0
  174. package/src/world-package.ts +469 -0
  175. package/src/world-passes.ts +582 -0
  176. package/src/world-region.ts +17 -0
  177. package/src/world-terrain-splat.ts +564 -0
  178. package/src/world-tiles.ts +3826 -0
  179. package/src/world-topology.ts +370 -0
  180. package/src/world-validate.ts +48 -0
  181. package/src/world.ts +805 -0
  182. package/dist/gpu-readback-CMklJs6r.d.ts +0 -112
@@ -1,5 +1,5 @@
1
- import { Object3D, Matrix4, Camera } from 'three';
2
- import { MRTNode, Node } from 'three/webgpu';
1
+ import { Vector2, Texture, RenderTarget, Object3D, Matrix4, Camera, BufferGeometry, DepthTexture } from 'three';
2
+ import { MRTNode, Node, StorageBufferAttribute, ReadbackBuffer } from 'three/webgpu';
3
3
 
4
4
  /**
5
5
  * Host-boundary counters, default-off, on the frame budget's own record.
@@ -26,11 +26,19 @@ import { MRTNode, Node } from 'three/webgpu';
26
26
  * Wrapping every method of a command encoder is not free — it is one extra JS call per command, and
27
27
  * this is why the counters ride the same opt-in flag as the spans rather than being always on.
28
28
  */
29
- /** One frame's boundary counts. Every field is absent when the platform cannot report it. */
29
+ /**
30
+ * One frame's boundary counts, plus the simulation tick it closed on.
31
+ *
32
+ * Every boundary field is absent when the platform cannot report it. `simulationTick` is not a
33
+ * platform reading: it is the loop's fixed-step count, absent when the caller fed none, and it
34
+ * rides here so a plain frame-budget window can be joined to the simulation without the spans flag.
35
+ */
30
36
  interface IFrameCounters {
31
37
  readonly gpuBytes?: number;
32
38
  readonly hostCalls?: number;
33
39
  readonly jsAllocBytes?: number;
40
+ /** The loop's fixed-step count at the frame's end; absent when the caller did not feed one. */
41
+ readonly simulationTick?: number;
34
42
  }
35
43
  /** The slice of a WebGPU device this reads. Structural, so a test can stand in a fake. */
36
44
  interface ICounterDevice {
@@ -74,17 +82,115 @@ declare class FrameCounters {
74
82
  * Measurement, not policy: installing this alters no draw. `install` answers `undefined` on a
75
83
  * renderer whose `info.render` cannot be read, and a consumer must then report the pass split as
76
84
  * absent rather than zero.
85
+ *
86
+ * The main pass's own draws are also split by where their mesh came from, counted at the one place
87
+ * a draw is counted — `info.update`, which every backend calls per submitted draw with the object
88
+ * that owns it — so the sources sum to `draws` by construction instead of by an estimate beside it.
77
89
  */
78
90
  /** The named kinds of a render pass. Closed on purpose: a consumer bounds a known kind. */
79
91
  declare const FRAME_PASS_KINDS: readonly ["main", "shadow", "reflection", "nested"];
80
92
  type FramePassKind = (typeof FRAME_PASS_KINDS)[number];
81
- /** One render call's own submissions, attributed to its innermost active render call. */
93
+ /**
94
+ * Where a main-pass draw's mesh came from. Closed, and `other` is the default.
95
+ *
96
+ * Each entry is a system that owns its meshes and writes the origin on them, so the split reads as
97
+ * an answer about systems rather than about geometry: `gpuScene` and `bundles` are `WorldCells`' two
98
+ * ways of drawing one main batch (a GPU-dressed key, and the same mesh replayed from the world's
99
+ * bundle), `terrain` is every mesh `world-tiles.ts` creates, `proxies` is the shadow halves and the
100
+ * whole-map impostor aggregates, `chunks` is a hand-placed chunk's own draws, `instanced` is a main
101
+ * batch the GPU scene never dressed, and `sky` is a daylight rig's sky box. What is left in `other`
102
+ * is a mesh no world system claimed — a character, a prop, a water surface the game loaded — which is
103
+ * the bucket that has to be small enough to be worth naming one draw at a time.
104
+ */
105
+ declare const MAIN_DRAW_SOURCES: readonly ["gpuScene", "bundles", "terrain", "proxies", "chunks", "instanced", "sky", "other"];
106
+ type MainDrawSource = (typeof MAIN_DRAW_SOURCES)[number];
107
+ /**
108
+ * One render call's own submissions, attributed to its innermost active render call.
109
+ *
110
+ * `drawsBySource` is `main`'s own draws by origin, in the frame's counts rather than in percentiles:
111
+ * it sums to `draws` for the frame, which is the claim the split exists to answer. Absent when the
112
+ * renderer named no object for one of those draws, because a split that guessed where a draw came
113
+ * from would read as a measurement.
114
+ */
82
115
  interface IRenderPassSample {
83
116
  readonly draws: number;
117
+ readonly drawsBySource?: Readonly<Partial<Record<MainDrawSource, number>>>;
84
118
  readonly kind: FramePassKind;
85
119
  readonly triangles: number;
86
120
  }
87
121
 
122
+ type PlatformRuntime = "web" | "native";
123
+ type PlatformOS = "android" | "ios" | "linux" | "macos" | "windows" | "unknown";
124
+ type PlatformFormFactor = "mobile" | "desktop" | "unknown";
125
+ interface IPlatformInfo {
126
+ readonly runtime: PlatformRuntime;
127
+ readonly os: PlatformOS;
128
+ readonly formFactor: PlatformFormFactor;
129
+ readonly maxTouchPoints: number;
130
+ }
131
+ declare function getPlatform(): Readonly<IPlatformInfo>;
132
+ declare function isWeb(): boolean;
133
+ declare function isNative(): boolean;
134
+ declare function isMobile(): boolean;
135
+ declare function isTouchscreenAvailable(): boolean;
136
+
137
+ /**
138
+ * One rule for what `display.maxFps` means when a game does not say.
139
+ *
140
+ * A template that shipped `maxFps: 60` taught every agent to copy the line, and every 120 Hz
141
+ * desktop then ran its game at half the panel it was sitting on — a default that is a constant the
142
+ * author is told to revisit later is a bug, not an option. So the default follows the display,
143
+ * capped at 120 on desktop and web, and stays 60 on mobile where the ceiling is power and heat
144
+ * rather than pixels. An explicit number still wins and `0` still removes the ceiling.
145
+ *
146
+ * **A browser has no refresh-rate API**, so "follows the display" is a measurement: the median
147
+ * interval between presented frames over the frame budget's first window is the panel's period,
148
+ * because on the web one rAF callback is one vblank. A native host says its own rate through the
149
+ * present counter, which is the only series there that counts displays rather than loop
150
+ * iterations. Both arrive as `measuredRefreshHz`; until one does, the answer is 60 and says so.
151
+ */
152
+
153
+ /** What a game gets before anything has been measured, and all a mobile gets. */
154
+ declare const DEFAULT_TARGET_FPS = 60;
155
+ /** The desktop and web ceiling, whatever the panel runs at. */
156
+ declare const MAX_TARGET_FPS = 120;
157
+ /**
158
+ * Where a resolved target came from, so a harness can assert the *rule* and not just the number:
159
+ * `"config"` is the game naming it, `"display"` a measured panel rate, `"mobile-default"` the
160
+ * mobile power ceiling, and `"fallback"` the 60 held until a measurement exists. An unmeasured 60
161
+ * is not the display's rate and does not report as one.
162
+ */
163
+ type TargetFpsSource = "config" | "display" | "fallback" | "mobile-default";
164
+ /** A resolved frame budget: the rate the loop holds, and what decided it. */
165
+ interface ITargetFps {
166
+ readonly targetFps: number;
167
+ readonly source: TargetFpsSource;
168
+ }
169
+ /** Whatever holds `display.maxFps` — `IGameConfig`, `IThreeNativeConfig`, or a bare object. */
170
+ interface ITargetFpsConfig {
171
+ readonly display?: {
172
+ readonly maxFps?: number | undefined;
173
+ } | undefined;
174
+ }
175
+ /** Only the one field the rule reads, so a caller need not hold a whole `IPlatformInfo`. */
176
+ type ITargetFpsPlatform = Pick<IPlatformInfo, "formFactor">;
177
+ /**
178
+ * The nearest common refresh rate, never above `MAX_TARGET_FPS`.
179
+ *
180
+ * A measured 59.94 Hz panel and a measured 60 Hz one are the same panel, and a value the engine
181
+ * invents rather than reads is a value no display can be asked to hold.
182
+ */
183
+ declare function snapRefreshRate(refreshHz: number): number;
184
+ /**
185
+ * The single reader of `display.maxFps`, used by the loop, the resolution scaler, the scene-shape
186
+ * warning, the frame-budget marker and the templates.
187
+ *
188
+ * `measuredRefreshHz` is the display's own rate when the platform can say it, and is what turns
189
+ * `"fallback"` into `"display"`. A negative or non-finite configured rate throws rather than
190
+ * quietly falling back: a config the engine ignored is worse than a config it rejected.
191
+ */
192
+ declare function resolveTargetFps(config: ITargetFpsConfig | undefined, platform: ITargetFpsPlatform | undefined, measuredRefreshHz?: number): ITargetFps;
193
+
88
194
  /**
89
195
  * Per-presented-frame cost attribution, on by default, for every platform.
90
196
  *
@@ -142,6 +248,7 @@ interface IFramePhaseSample {
142
248
  * convention off does not turn its measurement off.
143
249
  */
144
250
  interface IFrameSurfaceState {
251
+ readonly resolutionSubrect?: boolean;
145
252
  /** The applied drawing-buffer scale, in `(0, 1]`. */
146
253
  readonly resolutionScale: number;
147
254
  /**
@@ -173,15 +280,49 @@ interface IFrameBudgetSummary {
173
280
  readonly p99: number;
174
281
  readonly max: number;
175
282
  }
283
+ /** Where one resolved frame's GPU milliseconds went. Closed on purpose, like the phases. */
284
+ declare const FRAME_GPU_BUCKETS: readonly ["main", "shadow", "other", "compute"];
285
+ type FrameGpuBucket = (typeof FRAME_GPU_BUCKETS)[number];
286
+ /** One frame's GPU milliseconds per bucket; a bucket the device did not resolve is absent. */
287
+ type IFrameGpuBucketSample = Partial<Record<FrameGpuBucket, number>> & {
288
+ /**
289
+ * Shadow passes the frame recorded, from the producer. `0` means the frame drew no shadow and its
290
+ * `shadow` bucket is a known zero; `> 0` means it rendered one. Absent when the source cannot say,
291
+ * and no frame is then counted as rendered.
292
+ */
293
+ readonly shadowPasses?: number;
294
+ };
176
295
  /**
177
296
  * One render-pass kind's submissions across a window, so a change that trades triangles for CPU is
178
297
  * visible in the same report as the milliseconds it traded for.
179
298
  */
180
299
  interface IFrameBudgetPassSummary {
181
300
  readonly draws: IFrameBudgetSummary;
301
+ /**
302
+ * The main pass's own draws per origin, summarised like every other series in this window.
303
+ *
304
+ * The per-frame counts sum to `draws` exactly, which is the invariant the split exists to answer;
305
+ * the percentiles below do not have to, because a source that draws on some frames and not others
306
+ * has a median over its own frames rather than over the window's. A source no frame drew is
307
+ * absent. Absent altogether — never a set of zeros — when the renderer named no object behind one
308
+ * of the pass's draws, which is the same rule the pass record itself follows. One exception to the
309
+ * sum: a world with bundles on counts its replays here, and three never traverses a replay, so the
310
+ * sources can exceed `draws`; the sum holds for the sources that went through the per-draw path.
311
+ */
312
+ readonly drawsBySource?: Readonly<Partial<Record<MainDrawSource, IFrameBudgetSummary>>>;
182
313
  /** Frames in the window that submitted a pass of this kind. */
183
314
  readonly frames: number;
315
+ /**
316
+ * Three's CPU figure: `instanceCount * count / 3` per draw, where an indirect batch's `count` is
317
+ * the merged geometry's capacity. An upper bound over what the GPU could select.
318
+ */
184
319
  readonly triangles: IFrameBudgetSummary;
320
+ /**
321
+ * What the GPU selected, main pass only: the streamed world's own indirect tally, beside the
322
+ * figure above so a reader of the pass record can tell which of the two it is holding. Absent
323
+ * rather than zero when the world reported no tally — see `mainGpuTriangles`.
324
+ */
325
+ readonly gpuTriangles?: number;
185
326
  }
186
327
  /**
187
328
  * One reported window of the frame meter.
@@ -198,10 +339,21 @@ interface IFrameBudgetPassSummary {
198
339
  * it were a player's — `threenative-playtest perf` refuses to (`TN_PERF_VIRTUAL_DISPLAY`).
199
340
  */
200
341
  interface IFrameBudgetWindow {
342
+ /** Browser Long Tasks, independent of vsync/GPU waits. Unavailable on hosts without this API. */
343
+ readonly longTasks: {
344
+ readonly available: false;
345
+ } | {
346
+ readonly available: true;
347
+ readonly count: number;
348
+ readonly longestMs: number;
349
+ readonly afterFirstFrameMs: number;
350
+ };
201
351
  /** 1 for the first reported window, incrementing thereafter. */
202
352
  readonly window: number;
203
353
  /** Loop frames counted in this window, hitches excluded — one per present on the web. */
204
354
  readonly frames: number;
355
+ /** Fixed simulation ticks in this window multiplied by the loop's step, when supplied. */
356
+ readonly simulatedSeconds?: number;
205
357
  /** Frames excluded from the window because their present gap exceeded `hitchMs`. */
206
358
  readonly hitches: number;
207
359
  /**
@@ -241,12 +393,45 @@ interface IFrameBudgetWindow {
241
393
  * is absent; `frames` says how many frames did.
242
394
  */
243
395
  readonly passes?: Readonly<Partial<Record<FramePassKind, IFrameBudgetPassSummary>>>;
396
+ /**
397
+ * Instances and triangles the GPU actually selected in the main pass, from the streamed world's
398
+ * own indirect-args tally when it has one.
399
+ *
400
+ * These are the honest counterpart of `passes.main`: three's `renderer.info.render.triangles`
401
+ * counts a mesh's CPU window/capacity for an indirect draw, so `passes.main.triangles` is an upper
402
+ * bound over what the GPU could draw, while `mainGpuTriangles` is the sum over the indirect
403
+ * records of `instanceCount x indexCount / 3` — what the kernel selected. Main pass only: shadow
404
+ * passes are not tallied. Absent, never zero, before the first sample lands.
405
+ */
406
+ readonly mainGpuInstances?: number;
407
+ readonly mainGpuTriangles?: number;
244
408
  /**
245
409
  * The resolution and sampling this window's frames were drawn at, when the loop reported one.
246
410
  * Absent rather than defaulted: a consumer asserting on it must fail loudly instead of reading
247
411
  * a fabricated `1.0` that no frame was ever drawn at.
248
412
  */
249
413
  readonly surface?: IFrameSurfaceState;
414
+ /**
415
+ * The rate the loop is holding, and what decided it, when the engine resolved one.
416
+ *
417
+ * Two fields rather than an object, and a harness reads them without unwrapping anything: a
418
+ * number nobody can place (`targetSource: "fallback"`) is the difference between a game holding
419
+ * its panel and a game settling for 60, and only this line says which one happened.
420
+ */
421
+ readonly targetFps?: number;
422
+ readonly targetSource?: TargetFpsSource;
423
+ /**
424
+ * Frames in this window that ran past the target frame (`1000 / targetFps`, the target this
425
+ * window started with): `render` over every counted frame's render phase, `gpu` over the frames
426
+ * with a resolved GPU sample. A pooled p95 is under the target exactly when at most 5 % of the
427
+ * pooled frames are, which window quantiles can only bound (PRD-478). Absent until a target is
428
+ * known.
429
+ */
430
+ readonly overTarget?: {
431
+ readonly frameMs: number;
432
+ readonly gpu: number;
433
+ readonly render: number;
434
+ };
250
435
  /**
251
436
  * GPU milliseconds per resolved frame in this window, from `timestamp-query`, summarised like a
252
437
  * phase — mean/p50/p95/p99/max over the frames the device actually reported.
@@ -264,6 +449,13 @@ interface IFrameBudgetWindow {
264
449
  * every frame is stale reports `gpu` absent rather than the last reading looking current.
265
450
  */
266
451
  readonly gpuStale: number;
452
+ /**
453
+ * Frames in the window the renderer declined to draw (the Wasm web engine holds at most two drawn
454
+ * frames on the GPU). Their render phase is near zero, so `phases.render` over the window reads
455
+ * cheaper than the frames that were drawn; divide by `frames - renderSkips` for a drawn frame's cost.
456
+ * Absent, not zero, when the renderer drew every frame.
457
+ */
458
+ readonly renderSkips?: number;
267
459
  /**
268
460
  * The window mean of `gpu`, when present. The scalar the resolution scaler reads.
269
461
  *
@@ -271,30 +463,79 @@ interface IFrameBudgetWindow {
271
463
  * one series rather than a second instantaneous read.
272
464
  */
273
465
  readonly gpuMs?: number;
466
+ /** Resolved renderer-frame range behind this window; unavailable for unframed samples. */
467
+ readonly gpuFrames?: {
468
+ readonly first: number;
469
+ readonly last: number;
470
+ };
274
471
  /** Age of the most recent resolved GPU timestamp in Three.js frame IDs; absent means unobservable. */
275
472
  readonly gpuAgeFrames?: number;
276
473
  /**
277
- * The frame's boundary counts, when something counted them.
474
+ * GPU milliseconds per resolved frame, split by where the device spent them: the main scene
475
+ * pass, every shadow pass, everything else in the render pool (post chain, reflections, HUD) and
476
+ * the compute pool. Each is the window's p50 over the frames that resolved it, one decimal.
477
+ *
478
+ * `gpu` is their sum's series; these say which pass owns it. Absent rather than zero when that
479
+ * bucket never resolved — an unmeasured pass and a free one are different facts — so
480
+ * `gpuMain + gpuShadow + gpuOther` reconciles with `gpuMs` only when all three are present.
481
+ */
482
+ readonly gpuMain?: number;
483
+ readonly gpuShadow?: number;
484
+ readonly gpuOther?: number;
485
+ readonly gpuCompute?: number;
486
+ /**
487
+ * The shadow bucket's p95 and coverage over **every** frame that resolved a shadow reading,
488
+ * known-zero frames included, so the p95 can sit at zero while the shadow renders are expensive.
489
+ * Kept for compatibility beside {@link gpuShadowRendered}, which is the same tail over the frames
490
+ * that actually rendered a shadow — the distribution the phase comparison should read.
491
+ */
492
+ readonly gpuShadowP95?: number;
493
+ readonly gpuShadowSamples?: number;
494
+ /**
495
+ * The shadow bucket's distribution over the frames that **actually rendered a shadow**, distinct
496
+ * from the known-zero frames the p50 and all-frame p95 above include.
497
+ *
498
+ * `samples` is how many frames rendered one, so observed renders are tellable from frames that
499
+ * drew none (`gpuShadowSamples - gpuShadowRendered.samples`). Absent, never a zeroed summary, when
500
+ * no rendered shadow resolved: a render that cost 0 ms is still a render, and only the producer's
501
+ * own `shadowPasses` record says one happened, so the count is not guessed from `shadow > 0`.
502
+ */
503
+ readonly gpuShadowRendered?: IFrameBudgetSummary;
504
+ /** Pyramid build GPU milliseconds per resolved build, including the depth copy/resolve. */
505
+ readonly gpuPyramid?: IFrameBudgetSummary;
506
+ /**
507
+ * The frame's boundary counts, when something counted them, plus the simulation tick the window
508
+ * closed on when the loop fed one.
278
509
  *
279
- * Each series is absent when nothing measured it, and a series present with zero samples is not
280
- * possible: an uncounted frame and a frame that crossed the boundary zero times are different
281
- * facts, and a fabricated zero merges them. `hostCalls` and `gpuBytes` come from
510
+ * Each boundary series is absent when nothing measured it, and a series present with zero samples
511
+ * is not possible: an uncounted frame and a frame that crossed the boundary zero times are
512
+ * different facts, and a fabricated zero merges them. `hostCalls` and `gpuBytes` come from
282
513
  * `FrameCounters`; `jsAllocBytes` needs a platform that publishes `performance.memory`.
514
+ * `simulationTick` is not a platform reading — it is the loop's latest fixed-step count, so the
515
+ * object is present whenever `addCounters` carried a tick even with no boundary field measured.
283
516
  */
284
517
  readonly counters?: {
285
518
  readonly hostCalls?: IFrameBudgetSummary;
286
519
  readonly gpuBytes?: IFrameBudgetSummary;
287
520
  readonly jsAllocBytes?: IFrameBudgetSummary;
521
+ readonly simulationTick?: number;
288
522
  };
289
523
  }
524
+ interface IFrameBudgetSimulation {
525
+ readonly tick: () => number;
526
+ readonly step: number;
527
+ }
290
528
  interface IFrameBudgetOptions {
291
- /** Presented frames per report window. Default 300. */
529
+ /** Simulation ticks per report window when a clock is supplied, otherwise presented frames. Default 300. */
292
530
  readonly reportEvery?: number;
531
+ /** Minimum measured rendered frames per report window. Default 1. */
532
+ readonly minFrames?: number;
533
+ readonly simulation?: IFrameBudgetSimulation;
293
534
  /** A present gap at or above this is a hitch, not a frame. Default 2000 ms. */
294
535
  readonly hitchMs?: number;
295
536
  /** Ring capacity per series. Default 1024. */
296
537
  readonly capacity?: number;
297
- /** Where marker lines go. Default `console.log`. */
538
+ /** Where marker lines go. Default `console.log`. In defineGame, also receives all window telemetry; without a custom sink its existing info/warn severities remain. */
298
539
  readonly report?: (line: string) => void;
299
540
  /** Wall clock for hitch markers. Default `Date.now`. */
300
541
  readonly wallClock?: () => number;
@@ -309,6 +550,13 @@ interface IFrameBudgetOptions {
309
550
  * loop, which is the only place that knows both the renderer and the window boundary.
310
551
  */
311
552
  readonly readSurface?: () => IFrameSurfaceState;
553
+ /**
554
+ * The engine's resolved frame budget, read once per reported window.
555
+ *
556
+ * Wired by the game, which owns the rule and the panel measurement behind it. A window with no
557
+ * resolver reports no target rather than a default that looks measured.
558
+ */
559
+ readonly readTarget?: () => ITargetFps | undefined;
312
560
  /**
313
561
  * Frames the display has presented so far, when the platform can say.
314
562
  *
@@ -319,17 +567,29 @@ interface IFrameBudgetOptions {
319
567
  readonly readPresentCount?: () => number | undefined;
320
568
  /** Reads the successful GPU query frame age, not the age of the last resolve attempt. */
321
569
  readonly readGpuAgeFrames?: () => number | undefined;
570
+ /**
571
+ * The GPU-selected main-pass instance and triangle count, read once per reported window.
572
+ *
573
+ * Wired by the game from the streamed world's own tally; `undefined` until its first sample lands
574
+ * or when the world has none, so a window reports absent rather than a fabricated zero.
575
+ */
576
+ readonly readGpuTally?: () => {
577
+ readonly instances: number;
578
+ readonly triangles: number;
579
+ } | undefined;
322
580
  }
323
581
  /**
324
582
  * Accumulates one frame at a time and reports windowed attribution.
325
583
  *
326
584
  * The caller is the frame loop; the sequence per frame is
327
585
  * `beginFrame` → `markSimulationEnd` → (`addRender` / `addOverlay` / `addUi`) → `endFrame`.
328
- * Calling them out of order throws rather than producing a plausible-looking split.
586
+ * Calling them out of order throws rather than producing a plausible-looking split. The one
587
+ * exception is `addSimulation`, which reports simulation that ran outside any frame — see it.
329
588
  */
330
589
  declare class FrameBudget {
331
590
  #private;
332
591
  readonly reportEvery: number;
592
+ readonly minFrames: number;
333
593
  readonly hitchMs: number;
334
594
  constructor(options?: IFrameBudgetOptions);
335
595
  /**
@@ -337,10 +597,31 @@ declare class FrameBudget {
337
597
  * clock, which is not the same as `nowMs` and is what the interval between frames comes from.
338
598
  * @param nowMs the monotonic clock at callback entry.
339
599
  */
600
+ dispose(): void;
340
601
  beginFrame(timestampMs: number, nowMs: number): void;
341
602
  /** The boundary between the fixed-step simulation and everything the render phase does. */
342
603
  markSimulationEnd(nowMs: number, substeps: number): void;
604
+ /**
605
+ * Charges one counted simulation batch — the loop's `advance(ticks)`, which is how a tick-counted
606
+ * playtest run simulates at all — to this window's `update` and `substeps`.
607
+ *
608
+ * A batch is not a frame. It presents nothing, so it must not count as one: no frame in the
609
+ * window, no present interval, no GPU sample, no hitch however long it blocked, and no window
610
+ * boundary. Opening a metered frame around it instead put half of a fixed-step run's windows into
611
+ * the frame and render percentiles as zero-millisecond frames that drew nothing, and closed a
612
+ * "300-frame" window on 300 metered frames rather than 300 presented ones — which is how a
613
+ * 300-frame window came to hold ~20 GPU timestamp samples instead of ~37.
614
+ *
615
+ * Inside a live frame — the frozen prime's settle, which is `advance()` called from inside the
616
+ * frame that armed it — the batch's milliseconds are already inside that frame's own measurement
617
+ * and are not charged a second time; only its steps are added, so the frame reports it exactly
618
+ * once. Its blocking cost reaches the window either way: through the enclosing frame's `update`,
619
+ * or here.
620
+ */
621
+ addSimulation(ms: number, ticks: number): void;
343
622
  addRender(ms: number): void;
623
+ /** The renderer returned without drawing this frame; counted once per frame in the window's `renderSkips`. */
624
+ addRenderSkip(): void;
344
625
  addOverlay(ms: number): void;
345
626
  addUi(ms: number): void;
346
627
  /**
@@ -356,12 +637,27 @@ declare class FrameBudget {
356
637
  * Once per frame. A window with no reading at all reports `gpu` absent, never a zero.
357
638
  */
358
639
  addGpuMs(ms: number | undefined, frame?: number): void;
640
+ /** Record one freshly resolved pyramid build, independently of the render pool's cadence. */
641
+ addGpuPyramidMs(ms: number | undefined): void;
642
+ /**
643
+ * Records where one resolved frame's GPU time went, from the per-pass timestamp split.
644
+ *
645
+ * Alongside `addGpuMs`, once per frame. A bucket the producer could not attribute is left out
646
+ * rather than passed as zero: an unmeasured pass and a free one are different facts, and the
647
+ * p50 of a bucket that was never measured is absent from the window. An unknown bucket name
648
+ * throws rather than being dropped, the same fail-closed rule as a phase.
649
+ */
650
+ addGpuBucketMs(sample: IFrameGpuBucketSample): void;
359
651
  /**
360
652
  * Records the frame's host-boundary counts, from `FrameCounters` or any other source.
361
653
  *
362
654
  * At most one call per frame; a second replaces the first rather than summing, because the
363
655
  * counter's own reader already returns the frame's totals and summing two reads of one frame
364
656
  * would double it. A field the platform cannot report is left out of the series entirely.
657
+ *
658
+ * `simulationTick`, when present, must be a finite non-negative integer and is stored as the
659
+ * window's latest tick — never summed, and never cleared by a later call that omits it, so a
660
+ * plain `TN_FRAME_BUDGET` log can join a window's start and end ticks.
365
661
  */
366
662
  addCounters(counters: IFrameCounters): void;
367
663
  /**
@@ -463,8 +759,22 @@ interface IPipelineCensusEvent {
463
759
  /** Promise latency is retained as latency, never labelled native compiler time. */
464
760
  readonly promiseMs?: number;
465
761
  readonly error?: string;
762
+ /** Number of distinct Three node-builder states first observed during this render-object call. */
763
+ readonly nodeBuilds?: number;
466
764
  /** Whether this event settled before the first present boundary. */
467
765
  readonly beforeFirstPresent?: boolean;
766
+ /** Whether this event settled before the explicit warm-up completion boundary. */
767
+ readonly beforeWarmUpSettled?: boolean;
768
+ /** The most recent streamed warm-up scope that preceded this event. */
769
+ readonly afterWarmUpScope?: string;
770
+ }
771
+ /** A node-builder state observed even when Three reused an existing GPU pipeline. */
772
+ interface IPipelineNodeBuild {
773
+ readonly provenance: IPipelineProvenance;
774
+ readonly startedMs: number;
775
+ readonly beforeFirstPresent?: boolean;
776
+ readonly beforeWarmUpSettled?: boolean;
777
+ readonly afterWarmUpScope?: string;
468
778
  }
469
779
  interface IPipelineCensusCounts {
470
780
  readonly lookups: number;
@@ -475,6 +785,7 @@ interface IPipelineCensusCounts {
475
785
  readonly uniquePipelines: number;
476
786
  readonly recordedEvents: number;
477
787
  readonly droppedEvents: number;
788
+ readonly nodeBuilds: number;
478
789
  /**
479
790
  * Every creation seen at the device, including those attributed to a backend event. Absent
480
791
  * when the device could not be observed at all, so no reader mistakes silence for zero.
@@ -508,8 +819,26 @@ interface IPipelineCensus {
508
819
  readonly boundaryMs: number;
509
820
  readonly eventsSettled: number;
510
821
  };
822
+ readonly warmUpSettled?: {
823
+ readonly boundaryMs: number;
824
+ readonly eventsSettled: number;
825
+ readonly nodeBuilds: number;
826
+ readonly renderPipelineCreations: number;
827
+ };
828
+ readonly warmUpScopes?: readonly {
829
+ readonly label: string;
830
+ readonly boundaryMs: number;
831
+ readonly eventsSettled: number;
832
+ readonly nodeBuilds: number;
833
+ readonly renderPipelineCreations: number;
834
+ readonly firstDraw?: {
835
+ readonly nodeBuilds: number;
836
+ readonly renderPipelineCreations: number;
837
+ };
838
+ }[];
511
839
  readonly counts: IPipelineCensusCounts;
512
840
  readonly events: readonly IPipelineCensusEvent[];
841
+ readonly nodeBuilds?: readonly IPipelineNodeBuild[];
513
842
  readonly incompleteReasons: readonly string[];
514
843
  }
515
844
  interface IPipelineCensusOptions {
@@ -523,11 +852,14 @@ interface IPipelineCensusOptions {
523
852
  }
524
853
  interface IRendererHookTarget {
525
854
  backend?: unknown;
855
+ /** Three's renderer-owned node manager; absent on the WebGL2 renderer. */
856
+ _nodes?: unknown;
526
857
  renderObject?: (...args: unknown[]) => unknown;
527
858
  }
528
859
  /**
529
860
  * Create and install a bounded census. The returned object is intentionally small: renderers own
530
- * lifecycle and callers only need `snapshot()`, `withRenderObject()`, and `firstPresent()`.
861
+ * lifecycle and callers only need `snapshot()`, `withRenderObject()`, and the two lifecycle
862
+ * boundaries.
531
863
  */
532
864
  declare function createPipelineCensus(options: IPipelineCensusOptions): PipelineCensus;
533
865
  declare class PipelineCensus {
@@ -541,11 +873,110 @@ declare class PipelineCensus {
541
873
  dispose(): void;
542
874
  /** Wrap Three's public render-object method so compileAsync retains the authored pass id. */
543
875
  withRenderObject<T>(args: readonly unknown[], callback: () => T): T;
876
+ /** Begin the outer world render that can close target-bound streamed warm-up scopes. */
877
+ beginWorldFrame(root: object): void;
878
+ /** Close target-bound scopes only after the complete visible world frame has returned. */
879
+ endWorldFrame(root: object, completed: boolean): void;
544
880
  /** Mark the first renderer render call as the first-present boundary. */
545
881
  firstPresent(): void;
882
+ /** Mark the explicit shader warm-up as settled before the first measured world pass. */
883
+ warmUpSettled(): void;
884
+ /** Mark one repeatable streamed warm-up boundary; target-bound scopes close on their first world frame. */
885
+ warmUpScopeSettled(label: string, target?: object): void;
546
886
  snapshot(): IPipelineCensus;
547
887
  }
548
888
 
889
+ /** Exact per-call timings from Three 0.185.1's compute pool; Three owns all GPU resources. */
890
+ interface IComputeTimingSample {
891
+ readonly call: number;
892
+ readonly uid: string;
893
+ readonly gpuMs: number;
894
+ }
895
+ interface IComputeTimingReceipt {
896
+ readonly generation: object;
897
+ readonly calls: readonly number[];
898
+ /** Incomplete membership is absent; a completed receipt can be consumed only once. */
899
+ read(): readonly IComputeTimingSample[] | undefined;
900
+ }
901
+
902
+ /**
903
+ * Which family of GPU the adapter is: the start point of the look and of the pixel count.
904
+ *
905
+ * A fact about the machine, read from the four `adapter.info` fields and nothing else. What a
906
+ * class *looks like* is the game's own decision (`src/render/quality.ts`); this file only names the
907
+ * class, so a Mali-G52 phone and a Mali-G715 phone stop sharing one `mobile` flag.
908
+ *
909
+ * Measurement outranks this table. The first eligible frame-budget window moves the tier and the
910
+ * scale whichever class started them, so a wrong row costs windows, never a stuck look.
911
+ */
912
+ type GpuClass = "software" | "mobile-low" | "mobile-mid" | "mobile-high" | "integrated" | "discrete" | "unknown";
913
+ /** The four fields WebGPU's `adapter.info` carries. A field the platform omits is the empty string. */
914
+ interface IGpuAdapterFields {
915
+ readonly architecture: string;
916
+ readonly description: string;
917
+ readonly device: string;
918
+ readonly vendor: string;
919
+ }
920
+ interface IGpuClassification {
921
+ readonly class: GpuClass;
922
+ /** The first rule that matched, or `none` when no rule did. */
923
+ readonly rule: string;
924
+ readonly fields: IGpuAdapterFields;
925
+ }
926
+
927
+ interface IGpuFrameObservationOptions {
928
+ readonly maxFrames: number;
929
+ /** Timestamp slots, two per allocated pass; bounds pending plus queued observations. */
930
+ readonly maxQueries: number;
931
+ }
932
+ interface IGpuObservedQuery {
933
+ readonly uid: string;
934
+ readonly begin: number;
935
+ readonly end: number;
936
+ readonly ms: number;
937
+ }
938
+ interface IGpuObservedFrame {
939
+ readonly generation: number;
940
+ readonly batch: number;
941
+ /** Three render-query frame, which may belong to an overlay; not a world callback ID. */
942
+ readonly frame: number;
943
+ readonly ms: number;
944
+ readonly queries: readonly IGpuObservedQuery[];
945
+ }
946
+ interface IGpuFrameObservationStatus {
947
+ readonly generation: number;
948
+ readonly state: "active" | "stopped" | "failed" | "disposed";
949
+ readonly stopFrame: number | undefined;
950
+ readonly maxFrames: number;
951
+ readonly maxQueries: number;
952
+ readonly expectedFrames: number;
953
+ readonly expectedQueries: number;
954
+ readonly resolvedFrames: number;
955
+ readonly resolvedQueries: number;
956
+ readonly deliveredFrames: number;
957
+ readonly deliveredQueries: number;
958
+ readonly pendingFrames: number;
959
+ readonly pendingQueries: number;
960
+ /** Eligible allocated membership waiting behind an older resolve; included in capacity. */
961
+ readonly undrainedFrames: number;
962
+ readonly undrainedQueries: number;
963
+ readonly queuedFrames: number;
964
+ readonly queuedQueries: number;
965
+ readonly droppedFrames: number;
966
+ readonly droppedQueries: number;
967
+ /** Allocation attempts are not instrumented. Saturation cannot prove zero lost queries. */
968
+ readonly allocationLoss: "not-observed" | "unknown-after-saturation";
969
+ readonly ignoredCompletions: number;
970
+ readonly failure: string | undefined;
971
+ }
972
+ interface IGpuFrameObservation {
973
+ take(): readonly IGpuObservedFrame[];
974
+ status(): IGpuFrameObservationStatus;
975
+ /** Fence selection now; existing renderer resolves continue draining eligible older frames. */
976
+ stop(): void;
977
+ dispose(): void;
978
+ }
979
+
549
980
  /** The marker shared by alpha-antialiasing logs, playtests, and native diagnostics. */
550
981
  declare const ALPHA_ANTIALIASING_MARKER = "TN_ALPHA_ANTIALIASING";
551
982
  interface IAlphaAntialiasingReport {
@@ -560,6 +991,27 @@ interface IAlphaAntialiasingReport {
560
991
  readonly materials: number;
561
992
  }
562
993
 
994
+ interface IResolutionTextureView {
995
+ readonly viewFraction: Vector2;
996
+ readonly halfTexel: Vector2;
997
+ }
998
+ interface IResolutionSubrectNode {
999
+ setSize(width: number, height: number): void;
1000
+ }
1001
+ /** Owns capacity and viewport lifetime; generated render source owns sampling. */
1002
+ interface IResolutionSubrect {
1003
+ readonly active?: boolean;
1004
+ readonly view?: IResolutionTextureView;
1005
+ textureView(texture: Texture): IResolutionTextureView | undefined;
1006
+ activate?(scale: number): void;
1007
+ deactivate?(): void;
1008
+ setScale?(scale: number): void;
1009
+ setSize?(width: number, height: number): void;
1010
+ retain(node: IResolutionSubrectNode, targets: readonly RenderTarget[]): void;
1011
+ release(node: IResolutionSubrectNode): void;
1012
+ dispose(): void;
1013
+ }
1014
+
563
1015
  /** The output name shared by the scene pass and temporal consumers. */
564
1016
  declare const VELOCITY_OUTPUT_NAME = "velocity";
565
1017
  /**
@@ -569,6 +1021,8 @@ declare const VELOCITY_OUTPUT_NAME = "velocity";
569
1021
  * without making the game depend on either implementation.
570
1022
  */
571
1023
  interface IVelocityRenderPass {
1024
+ /** Physical attachments on Three passes; structural adapters may own them elsewhere. */
1025
+ readonly renderTarget?: Pick<RenderTarget, "textures" | "dispose">;
572
1026
  getMRT(): MRTNode | null;
573
1027
  getTextureNode(name?: string): Node;
574
1028
  setMRT(value: MRTNode | null): unknown;
@@ -599,6 +1053,17 @@ declare function velocityTexture(pass: IVelocityRenderPass): Node;
599
1053
  * @situation hand the provisioned velocity source through a composed temporal graph
600
1054
  */
601
1055
  declare function withVelocityContext<T>(node: T, source: Node): T;
1056
+ /**
1057
+ * How the render chain provisions the MRT velocity a temporal stage reads. The chain defaults to
1058
+ * {@link mrtVelocity}; a host that provisions velocity another way (an engine whose scene pass owns
1059
+ * the output) passes its own as `request.velocity.provision`.
1060
+ */
1061
+ interface IVelocityProvision {
1062
+ /** Ensures `pass` writes velocity and returns its texture node. */
1063
+ texture(pass: IVelocityRenderPass): Node;
1064
+ /** Hands the velocity source through the composed graph; `source` is the node `texture` returned. */
1065
+ attach<T>(node: T, source: Node): T;
1066
+ }
602
1067
  /**
603
1068
  * Captures instance matrices at the framework's pre-render boundary and enables previous data on
604
1069
  * every renderable in the graph. The previous snapshot is never the array the game writes next.
@@ -663,11 +1128,11 @@ interface IRenderChainVelocityResult {
663
1128
  interface IRenderChainRenderer {
664
1129
  readonly kind: RendererKind;
665
1130
  readonly raw: unknown;
666
- clearOutputNode?(): void;
1131
+ clearOutputNode?(expectedNode?: unknown): void;
667
1132
  /** Internal renderer seam used to turn on core-owned previous-frame bookkeeping for active temporal stages. */
668
1133
  setRenderChainVelocityEnabled?(enabled: boolean): void;
669
1134
  /** Install a graph and identify the authored world pass that follows the rendered scene root. */
670
- setOutputNode(node: unknown, worldPass?: unknown): void;
1135
+ setOutputNode: RenderOutputSetter;
671
1136
  }
672
1137
  /** Quality values are algorithm parameters, not appearance values. Templates own the latter. */
673
1138
  declare const RENDER_CHAIN_TIERS: {
@@ -695,6 +1160,12 @@ declare const RENDER_CHAIN_TIERS: {
695
1160
  interface IRenderChainVelocityRequest {
696
1161
  /** The scene pass that owns the shared velocity output. */
697
1162
  pass?: IVelocityRenderPass;
1163
+ /**
1164
+ * Optional: how the chain builds the velocity output on `pass` and hands it through the composed
1165
+ * graph. Defaults to core's own {@link mrtVelocity}, so a web game never names it; a host whose
1166
+ * scene pass owns the output differently passes its own.
1167
+ */
1168
+ provision?: IVelocityProvision;
698
1169
  /** Treat the renderer's MRT velocity output as provisioned. */
699
1170
  mrt?: boolean;
700
1171
  /** Treat objects carrying `userData.useVelocity === true` as provisioned. */
@@ -719,16 +1190,32 @@ interface IRenderChainRequest {
719
1190
  interface IRenderChainStageContext {
720
1191
  readonly tier: RenderChainTier;
721
1192
  readonly velocity: IRenderChainVelocityReport;
1193
+ /** Mutable target fractions supplied to generated stages for sub-rectangle sampling. */
1194
+ readonly resolutionSubrect?: IResolutionTextureView;
722
1195
  /** TSL source handed to temporal stages when the request owns a scene pass. */
723
1196
  readonly velocityNode?: Node;
724
1197
  readonly quality: (typeof RENDER_CHAIN_TIERS)[RenderChainTier];
725
1198
  }
726
1199
  interface IRenderChainStage {
1200
+ readonly supportsResolutionSubrect?: boolean;
727
1201
  readonly name: RenderChainStageId;
728
1202
  /** Place an authored stage immediately before this built-in or supplied stage. */
729
1203
  readonly before?: RenderChainStageId;
730
1204
  /** Place an authored stage immediately after this built-in or supplied stage. */
731
1205
  readonly after?: RenderChainStageId;
1206
+ /**
1207
+ * This stage reads display-referred colour, so the chain installs the graph with the renderer's
1208
+ * automatic output transform switched off and the stage applies that transform itself.
1209
+ *
1210
+ * Mechanism, not look. Some effects are defined against the sRGB picture — a `.cube` table, a
1211
+ * sharpening or edge filter — and bending scene-referred light into that domain costs precision
1212
+ * instead of buying anything: measured on an 8-bit table, a bijective log shaper costs 2–4
1213
+ * 8-bit steps per channel against under 1 for the transform this names (PRD-492).
1214
+ *
1215
+ * The stage therefore runs last, and may not declare an anchor: a stage placed after it would
1216
+ * receive display-referred colour it was not written for.
1217
+ */
1218
+ readonly afterOutputTransform?: boolean;
732
1219
  readonly build: (input: unknown, context: IRenderChainStageContext) => unknown;
733
1220
  /** Stages below this tier are named as dropped instead of silently changing the graph. */
734
1221
  readonly minimumTier?: RenderChainTier;
@@ -776,6 +1263,7 @@ interface IRenderChainBudgetWindow {
776
1263
  };
777
1264
  }
778
1265
  interface IRenderChainOptions {
1266
+ readonly resolutionSubrect?: IResolutionSubrect;
779
1267
  readonly renderer: IRenderChainRenderer;
780
1268
  readonly input?: unknown;
781
1269
  /** Explicit scene pass for output retargeting; avoids traversing a composed graph to find it. */
@@ -825,7 +1313,39 @@ declare class RenderChain {
825
1313
  dispose(): void;
826
1314
  }
827
1315
 
1316
+ /** The standard buffer fields this renderer seam verifies; the device handle stays opaque. */
1317
+ interface IRendererStorageBuffer {
1318
+ readonly size: number;
1319
+ readonly usage: number;
1320
+ readonly mapState: string;
1321
+ destroy(): void;
1322
+ }
1323
+ /** Exclusive allocation receipt. The solver borrows its handles and never destroys them. */
1324
+ interface IStorageBufferLease {
1325
+ readonly device: object;
1326
+ readonly buffer: IRendererStorageBuffer;
1327
+ readonly byteLength: number;
1328
+ readonly released: boolean;
1329
+ assertCurrent(): void;
1330
+ dispose(): void;
1331
+ }
1332
+
828
1333
  type RendererKind = "webgpu" | "webgl2";
1334
+ /** Owns one output-pipeline installation, not the lifetime of its input graph dependencies. */
1335
+ interface IRenderOutputInstallation {
1336
+ isCurrent(): boolean;
1337
+ dispose(): void;
1338
+ }
1339
+ /**
1340
+ * Where the transform goes when a stage does the renderer's job for it. The chain passes
1341
+ * `false` only when a stage that read display-referred colour actually ran.
1342
+ */
1343
+ interface IRenderOutputOptions {
1344
+ readonly outputColorTransform?: boolean;
1345
+ readonly resolutionSubrect?: IResolutionSubrect;
1346
+ }
1347
+ /** Union of callbacks preserves TypeScript's legacy void-callback return-value compatibility. */
1348
+ type RenderOutputSetter = ((node: unknown, worldPass?: unknown, options?: IRenderOutputOptions) => void) | ((node: unknown, worldPass?: unknown, options?: IRenderOutputOptions) => IRenderOutputInstallation);
829
1349
  /**
830
1350
  * Put transient meshes through the renderer's first-use shader path during loading.
831
1351
  *
@@ -866,6 +1386,12 @@ interface IRendererLike {
866
1386
  readonly compileCount?: number;
867
1387
  /** The bounded, fail-closed pipeline observation for this renderer, when enabled. */
868
1388
  readonly pipelineCensus?: () => IPipelineCensus;
1389
+ /** Marks the completion of the renderer's current scene warm-up attempt. */
1390
+ warmUpSettled?(): void;
1391
+ /** Marks a repeatable streamed warm-up boundary for the next first draw. */
1392
+ warmUpScopeSettled?(label: string, target?: Object3D): void;
1393
+ /** Performs one covered output-pipeline render without marking first present. */
1394
+ warmUpWorldPass?(scene: Object3D, camera: Camera, targetScene?: Object3D): void;
869
1395
  /**
870
1396
  * What alpha antialiasing did with the multisampled surface, and why, when it did nothing.
871
1397
  *
@@ -878,7 +1404,77 @@ interface IRendererLike {
878
1404
  * the `TN_ALPHA_ANTIALIASING` marker is printed either way, so nothing is only readable here.
879
1405
  */
880
1406
  alphaAntialiasing?: () => IAlphaAntialiasingReport;
881
- compute(node: unknown): void;
1407
+ /**
1408
+ * The `adapter.info` field value that identifies a CPU rasteriser — `swiftshader`, `llvmpipe`,
1409
+ * a `Microsoft Basic Render Driver` — when the adapter named one, else absent.
1410
+ *
1411
+ * Reading it needs `navigator.gpu`, so it is read here rather than in a game's render source.
1412
+ * It is a fact about the machine, not a look: which tier a game runs on a software adapter is
1413
+ * that game's own decision, and every tier name it might pick is already in its own
1414
+ * `src/render/quality.ts`. What this removes is the reason it could not make that decision
1415
+ * before its first expensive frame — a CPU rasteriser running a desktop render chain can lose
1416
+ * the device on the very first frame, which no adaptation after it survives.
1417
+ *
1418
+ * Absent means no software name was found, never that the adapter is hardware. The native host
1419
+ * exposes the same four `adapter.info` fields, so the same read works on every target.
1420
+ */
1421
+ readonly softwareAdapter?: string;
1422
+ /**
1423
+ * The GPU family the adapter belongs to, the rule that named it and the four raw `adapter.info`
1424
+ * fields it was read from; absent when no adapter reported (a WebGL2 fallback).
1425
+ *
1426
+ * A fact about the machine, like `softwareAdapter`, and the better input for a start tier: it
1427
+ * tells a Mali-G52 from a Mali-G715 and an iGPU from a discrete card, where `mobile` and
1428
+ * `software` cannot. `unknown` means no rule matched; treat it as the behaviour before this
1429
+ * existed. Measurement still outranks it, and the class only picks where the first window starts.
1430
+ */
1431
+ readonly gpuClass?: IGpuClassification;
1432
+ /** Advances the GPU sample once before a presented frame's simulation and render passes. */
1433
+ beginFrame?(): void;
1434
+ compute(node: unknown, span?: "depthPyramid"): void;
1435
+ /** Opt-in synchronous dispatch scope; consumes exact Three-owned query UID membership once resolved. */
1436
+ computeTiming?(operation: () => unknown, options?: {
1437
+ readonly maxCalls?: number;
1438
+ }): IComputeTimingReceipt;
1439
+ /**
1440
+ * Creates the GPU buffers these geometries draw from, through the backend's own attribute path,
1441
+ * and reports how many it created.
1442
+ *
1443
+ * `compileAsync` builds pipelines, not buffers: a streamed mesh's first draw is where its
1444
+ * attributes reach the device, and one chunk's first draw measured 230 ms of a frame for it. This
1445
+ * moves that to admission, one chunk at a time. WebGPU only — the WebGL fallback has no seam
1446
+ * this can call without inventing a GL enum — and absent or throwing answers 0, so the first
1447
+ * draw uploads exactly as it did before.
1448
+ */
1449
+ uploadAttributes?(geometries: Iterable<BufferGeometry>): number;
1450
+ /** Exclusive Float32 vec4 storage on the existing WebGPU device; release its receipt on scene exit. */
1451
+ storageBuffer?(attribute: StorageBufferAttribute): IStorageBufferLease;
1452
+ /**
1453
+ * Copies one streamed subtree's textures to the device, through three's own texture path, and
1454
+ * reports how many it took.
1455
+ *
1456
+ * The same argument as `uploadAttributes`, one resource class over: `compileAsync` builds
1457
+ * pipelines, not pixels, so a streamed chunk's textures reach the device inside `_renderObjectDirect`
1458
+ * on the frame the chunk first draws. On a Machinefall map-walk with three's internals counted per
1459
+ * render, that was 87 ms of a 94 ms first draw in one frame, 79 ms of 131 ms in another, and 519 ms
1460
+ * in a third — 10 renders of 19,000 hold the whole 2,574 ms the run spends on first draws.
1461
+ * `Textures.updateTexture` returns early when the texture is already at its current version, so this
1462
+ * is a move rather than a second upload, and a material the world shares with what is already on
1463
+ * screen costs one call and no work. WebGPU only — the WebGL fallback has no seam here — and
1464
+ * absent or throwing answers 0, so the first draw uploads exactly as it did before.
1465
+ */
1466
+ uploadTextures?(object: Object3D): number;
1467
+ /**
1468
+ * Prepares unique cold compressed textures before their first compile or draw. WebGPU uses
1469
+ * one upload lane, a measured 2 ms budget and at most 64 KiB per write; one final write may
1470
+ * overshoot the time budget. Await this gate before exposing the textures to rendering.
1471
+ * Original Texture/GPUTexture identities, formats and mip levels are retained. Cancellation
1472
+ * releases this caller's interest; another caller of the same texture may still complete.
1473
+ * Ordinary textures and the WebGL fallback retain their existing paths and report no work.
1474
+ * `onProgress` receives the completed unique compressed texture count after each preparation
1475
+ * promise resolves; queued textures and writes that have not settled receive no credit.
1476
+ */
1477
+ prepareTextures?(textures: Iterable<Texture>, signal?: AbortSignal, onProgress?: (completed: number) => void): Promise<number>;
882
1478
  /**
883
1479
  * Copies one GPU storage attribute back to the CPU, asynchronously.
884
1480
  *
@@ -886,14 +1482,29 @@ interface IRendererLike {
886
1482
  * must cast through `.raw` to read its own simulation will either not read it or read it wrong.
887
1483
  * The copy is asynchronous by nature — the caller gets the bytes some frames after the frame
888
1484
  * that produced them, and `GPUReadback` is what turns that latency into a reported number
889
- * instead of a silent one.
1485
+ * instead of a silent one. Pass a public ReadbackBuffer to own staging cleanup on rejected maps;
1486
+ * the returned bytes are copied before the caller disposes that target in finally.
1487
+ */
1488
+ readback(attribute: unknown, target?: ReadbackBuffer): Promise<ArrayBuffer>;
1489
+ /**
1490
+ * The scene pass's stored depth attachment and sample count, from an authored pass or three's
1491
+ * internal framebuffer target. `undefined` when neither has rendered a depth to read.
1492
+ *
1493
+ * Optional because a backend that cannot render into a target of its own has no scene-pass depth to
1494
+ * hand over. A cull reads this every dispatch: on the frame it answers, the texture holds what the
1495
+ * previous frame's pass wrote, because this is asked before the frame draws.
890
1496
  */
891
- readback(attribute: unknown): Promise<ArrayBuffer>;
1497
+ scenePassDepth?(): {
1498
+ readonly texture: DepthTexture;
1499
+ readonly width: number;
1500
+ readonly height: number;
1501
+ readonly samples?: number;
1502
+ } | undefined;
892
1503
  render(scene: Object3D, camera: Camera): void;
893
1504
  /** Draws after the world without clearing or passing through the world's output pipeline. */
894
1505
  renderOverlay(scene: Object3D, camera: Camera): void;
895
- /** Removes the output pipeline installed by a render-chain. */
896
- clearOutputNode?(): void;
1506
+ /** Legacy input-filtered clear; use an installation receipt for same-node replacement safety. */
1507
+ clearOutputNode?(expectedNode?: unknown): void;
897
1508
  /** Creates the core-owned chain seam without making generated render source import the package. */
898
1509
  createRenderChain?: (options: Omit<IRenderChainOptions, "renderer">) => RenderChain;
899
1510
  /** Feeds automatic render-chain tiers the completed frame-budget window. */
@@ -905,7 +1516,8 @@ interface IRendererLike {
905
1516
  /** Internal callback used by RenderChain; games should request velocity through the chain. */
906
1517
  setRenderChainVelocityEnabled?: (enabled: boolean) => void;
907
1518
  /** Installs a graph; pass the authored world pass when the graph contains auxiliary passes. */
908
- setOutputNode(node: unknown, worldPass?: unknown): void;
1519
+ setOutputNode: RenderOutputSetter;
1520
+ createResolutionSubrect?: () => IResolutionSubrect;
909
1521
  setSize(width: number, height: number, updateStyle?: boolean): void;
910
1522
  /**
911
1523
  * The GPU time the last resolved frame actually cost, in milliseconds, or `undefined` when the
@@ -932,6 +1544,49 @@ interface IRendererLike {
932
1544
  readonly frame: number;
933
1545
  readonly ms: number;
934
1546
  } | undefined;
1547
+ /**
1548
+ * Observes complete allocated render-query groups without changing ordinary sampling.
1549
+ * Frame IDs are Three query IDs, including any overlay draws; callers map world callbacks.
1550
+ * Capacities bound undrained, pending and queued membership. maxQueries counts timestamp
1551
+ * slots (two per pass). A failed receipt is sticky and must be disposed before replacement.
1552
+ * Requires timestamp-capable WebGPU and its existing asynchronous resolver.
1553
+ */
1554
+ observeGpuFrames?(options: IGpuFrameObservationOptions): IGpuFrameObservation;
1555
+ /**
1556
+ * GPU milliseconds of the last resolved compute frame, when the adapter reports one.
1557
+ *
1558
+ * The compute pool is a separate series from the render pool and `resolveGpuFrame` resolves it,
1559
+ * so a GPU simulation's cost is measurable instead of being charged to whatever render frame
1560
+ * happened to overlap. `undefined` for a WebGL2 fallback, an adapter without timestamps, or a
1561
+ * frame that ran no compute.
1562
+ */
1563
+ gpuComputeMs?(): number | undefined;
1564
+ /** Consume one fresh timestamped pyramid build, including its depth resolve; absent until resolved. */
1565
+ gpuPyramidMs?(): number | undefined;
1566
+ /**
1567
+ * The main render pass's GPU milliseconds, smoothed over fresh resolved samples, or `undefined`
1568
+ * while no reading is fresh.
1569
+ *
1570
+ * `gpuFrameMs` is the whole render pool, main plus every shadow, reflection, post and HUD pass;
1571
+ * the adaptive LOD control loop needs the main-pass share alone. `game.ts` splits the resolved
1572
+ * frame through the pass recorder and feeds the sample here with {@link noteGpuMainMs}. A
1573
+ * repeated frame id is a resolve still in flight and not a new reading, and with no fresh sample
1574
+ * for too long the value reads absent, so a caller never adapts on a stale number.
1575
+ */
1576
+ gpuMainMs?(): number | undefined;
1577
+ /**
1578
+ * Records one resolved frame's main-pass GPU milliseconds into {@link gpuMainMs}. Called once a
1579
+ * frame by `game.ts`; `ms` is `undefined` when the frame attributed no main-pass reading.
1580
+ */
1581
+ noteGpuMainMs?(ms: number | undefined, frame?: number): void;
1582
+ /**
1583
+ * The frame rate the game resolved as its target (`resolveTargetFps`), or `undefined` before one
1584
+ * is known or when it is uncapped. Budgets that are a share of a frame read it, so a frame that ran
1585
+ * faster than the target does not shrink what the next one may spend.
1586
+ */
1587
+ targetFps?(): number | undefined;
1588
+ /** Records the resolved target; called by `game.ts` when it resolves or retargets. */
1589
+ noteTargetFps?(fps: number): void;
935
1590
  /** Starts a resolve of the GPU timestamps for the frames drawn since the last call. */
936
1591
  resolveGpuFrame(): void;
937
1592
  /**
@@ -1001,4 +1656,4 @@ interface IRendererOptions {
1001
1656
  }>) => unknown;
1002
1657
  }
1003
1658
 
1004
- export { VELOCITY_PREVIOUS_INSTANCE_MATRICES as $, type IRenderChainStageContext as A, type IRenderChainVelocityMeasurement as B, type IRenderChainVelocityReport as C, DEFAULT_PIPELINE_CENSUS_LIMIT as D, type IRenderChainVelocityRequest as E, type FramePassKind as F, type IRenderChainVelocityResult as G, type IRenderPassSample as H, type IRendererLike as I, type IVelocityRenderPass as J, PIPELINE_CENSUS_VERSION as K, PipelineCensus as L, type PipelineCensusMode as M, type PipelineCensusStatus as N, RENDER_CHAIN_STAGE_ORDER as O, PIPELINE_CENSUS_CAPABILITY as P, RENDER_CHAIN_TIERS as Q, RENDER_CHAIN_MARKER as R, RenderChain as S, type RenderChainSource as T, type RenderChainStageId as U, type RenderChainStageName as V, type RenderChainTier as W, type RenderChainTierRequest as X, type RenderChainVelocitySource as Y, VELOCITY_OUTPUT_NAME as Z, VELOCITY_PREVIOUS_BONE_MATRICES as _, type IFrameBudgetWindow as a, VELOCITY_PREVIOUS_WORLD_MATRIX as a0, VelocityTracker as a1, counterDeviceOf as a2, createPipelineCensus as a3, ensureVelocityOutput as a4, prewarm as a5, readRenderChainObservation as a6, readRenderChainReport as a7, readVelocityPreviousBoneMatrices as a8, readVelocityPreviousMatrices as a9, readVelocityPreviousWorldMatrix as aa, velocityTexture as ab, withVelocityContext as ac, type IRendererOptions as ad, FRAME_BUDGET_MARKER as b, FRAME_BUDGET_PHASES as c, FRAME_HITCH_MARKER as d, FrameBudget as e, type FrameBudgetPhase as f, FrameCounters as g, type ICounterDevice as h, type IFrameBudgetOptions as i, type IFrameBudgetPassSummary as j, type IFrameBudgetSummary as k, type IFrameCounters as l, type IFramePhaseSample as m, type IPipelineCensus as n, type IPipelineCensusCounts as o, type IPipelineCensusEvent as p, type IPipelineCensusOptions as q, type IPipelineProvenance as r, type IPipelineShaderObservation as s, type IRenderChainApplied as t, type IRenderChainBudgetWindow as u, type IRenderChainDroppedStage as v, type IRenderChainOptions as w, type IRenderChainRenderer as x, type IRenderChainRequest as y, type IRenderChainStage as z };
1659
+ export { RENDER_CHAIN_TIERS as $, type IRenderChainDroppedStage as A, type IRenderChainOptions as B, type IRenderChainRenderer as C, DEFAULT_PIPELINE_CENSUS_LIMIT as D, type IRenderChainRequest as E, type FramePassKind as F, type IRenderChainStage as G, type IRenderChainStageContext as H, type IRendererLike as I, type IRenderChainVelocityMeasurement as J, type IRenderChainVelocityReport as K, type IRenderChainVelocityRequest as L, type IRenderChainVelocityResult as M, type ITargetFps as N, type IVelocityRenderPass as O, MAX_TARGET_FPS as P, type MainDrawSource as Q, PIPELINE_CENSUS_CAPABILITY as R, PIPELINE_CENSUS_VERSION as S, PipelineCensus as T, type PipelineCensusMode as U, type PipelineCensusStatus as V, type PlatformFormFactor as W, type PlatformOS as X, type PlatformRuntime as Y, RENDER_CHAIN_MARKER as Z, RENDER_CHAIN_STAGE_ORDER as _, type IFrameBudgetWindow as a, RenderChain as a0, type RenderChainSource as a1, type RenderChainStageId as a2, type RenderChainStageName as a3, type RenderChainTier as a4, type RenderChainTierRequest as a5, type RenderChainVelocitySource as a6, type TargetFpsSource as a7, VELOCITY_OUTPUT_NAME as a8, VELOCITY_PREVIOUS_BONE_MATRICES as a9, VELOCITY_PREVIOUS_INSTANCE_MATRICES as aa, VELOCITY_PREVIOUS_WORLD_MATRIX as ab, VelocityTracker as ac, counterDeviceOf as ad, createPipelineCensus as ae, ensureVelocityOutput as af, getPlatform as ag, isMobile as ah, isNative as ai, isTouchscreenAvailable as aj, isWeb as ak, prewarm as al, readRenderChainObservation as am, readRenderChainReport as an, readVelocityPreviousBoneMatrices as ao, readVelocityPreviousMatrices as ap, readVelocityPreviousWorldMatrix as aq, resolveTargetFps as ar, snapRefreshRate as as, velocityTexture as at, withVelocityContext as au, type IFrameBudgetSimulation as b, type IRenderPassSample as c, type IFramePhaseSample as d, type IPipelineCensus as e, type IRendererOptions as f, type IFrameBudgetOptions as g, DEFAULT_TARGET_FPS as h, FRAME_BUDGET_MARKER as i, FRAME_BUDGET_PHASES as j, FRAME_HITCH_MARKER as k, FrameBudget as l, type FrameBudgetPhase as m, FrameCounters as n, type ICounterDevice as o, type IFrameBudgetPassSummary as p, type IFrameBudgetSummary as q, type IFrameCounters as r, type IPipelineCensusCounts as s, type IPipelineCensusEvent as t, type IPipelineCensusOptions as u, type IPipelineProvenance as v, type IPipelineShaderObservation as w, type IPlatformInfo as x, type IRenderChainApplied as y, type IRenderChainBudgetWindow as z };