@threenative/core 0.3.6 → 0.3.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/README.md +3 -5
  2. package/capabilities.json +739 -50
  3. package/dist/{assets-CqvE429w.d.ts → assets-YUbXa3-Y.d.ts} +101 -2
  4. package/dist/{canvas-layer-C1-5CviZ.d.ts → canvas-layer-vCtanIeB.d.ts} +1 -1
  5. package/dist/{game-Jz4Fdoeb.d.ts → game-cb99J-YE.d.ts} +100 -31
  6. package/dist/hot.d.ts +4 -4
  7. package/dist/hot.js +23 -5
  8. package/dist/index.d.ts +1742 -29
  9. package/dist/index.js +22443 -12423
  10. package/dist/{model-lod-BDAUYgsS.d.ts → model-lod-CTpZ6imz.d.ts} +1 -1
  11. package/dist/net.js +39 -12
  12. package/dist/playtest.d.ts +4 -4
  13. package/dist/playtest.js +48 -9
  14. package/dist/react-css.js +23 -0
  15. package/dist/react.d.ts +2 -2
  16. package/dist/{renderer-9yEo9hPa.d.ts → renderer-rZm0hVqq.d.ts} +178 -5
  17. package/dist/ui-layer.d.ts +11 -2
  18. package/dist/ui-layer.js +76 -4
  19. package/dist/worker.d.ts +36 -0
  20. package/dist/worker.js +1088 -0
  21. package/dist/world.d.ts +11 -3
  22. package/dist/world.js +1117 -197
  23. package/mcp/animation-server.mjs +265 -0
  24. package/mcp/animation.mjs +22 -0
  25. package/mcp/call.mjs +105 -0
  26. package/mcp/devtools.mjs +5 -0
  27. package/mcp/engine-server.mjs +713 -37
  28. package/mcp/launch.mjs +3 -2
  29. package/mcp/servers.d.mts +2 -0
  30. package/mcp/servers.mjs +33 -8
  31. package/package.json +12 -8
  32. package/patches/three@0.185.1-prd269-upgrade.patch +308 -0
  33. package/patches/three@0.185.1.patch +481 -272
  34. package/src/animation-packet-state.ts +88 -0
  35. package/src/animation-pose-packet.ts +537 -0
  36. package/src/animation.ts +779 -31
  37. package/src/asset-cache.ts +719 -0
  38. package/src/assets.ts +521 -152
  39. package/src/audio.ts +29 -3
  40. package/src/auto-batch.ts +792 -0
  41. package/src/config.ts +2 -0
  42. package/src/frame-budget.ts +268 -2
  43. package/src/game.ts +525 -105
  44. package/src/grounding.ts +7 -6
  45. package/src/hot.ts +19 -5
  46. package/src/index.ts +381 -6
  47. package/src/input.ts +21 -2
  48. package/src/interpolation.ts +19 -1
  49. package/src/launch-diagnostics.ts +7 -2
  50. package/src/look/ao-multibounce.ts +29 -0
  51. package/src/look/ao-reach.ts +39 -0
  52. package/src/look/auto-exposure.ts +264 -0
  53. package/src/look/default-tone-mapping.ts +44 -0
  54. package/src/look/exposure-graph.ts +208 -0
  55. package/src/look/exposure-readback.ts +97 -0
  56. package/src/look/exposure-settings.ts +132 -0
  57. package/src/look/filmic-tone-mapping.ts +852 -0
  58. package/src/look/gi-registry.ts +55 -0
  59. package/src/look/local-exposure.ts +507 -0
  60. package/src/look/look-diagnostics.ts +24 -0
  61. package/src/look/motion-blur.ts +42 -0
  62. package/src/look/quality.ts +309 -0
  63. package/src/look/reflection-trace.ts +344 -0
  64. package/src/look/unreal-bloom.ts +295 -0
  65. package/src/look/vignette.ts +14 -0
  66. package/src/look/world-environment.ts +2033 -0
  67. package/src/loop.ts +25 -1
  68. package/src/merge-parts.ts +25 -10
  69. package/src/model-lod.ts +14 -0
  70. package/src/net-session.ts +58 -14
  71. package/src/ocean/spectral.ts +41 -7
  72. package/src/picking.ts +72 -5
  73. package/src/platform.ts +29 -1
  74. package/src/playtest.ts +54 -8
  75. package/src/profiling/FrameCounters.ts +166 -5
  76. package/src/profiling/FrameStages.ts +289 -0
  77. package/src/profiling/Spans.ts +39 -25
  78. package/src/profiling/debug-telemetry.ts +312 -0
  79. package/src/profiling/scene-warning.ts +42 -6
  80. package/src/projection-apply.ts +11 -3
  81. package/src/projection-content.ts +189 -0
  82. package/src/projection-marker.ts +6 -2
  83. package/src/projection-plan.ts +279 -28
  84. package/src/projection-skinned.ts +620 -5
  85. package/src/projection-stability.ts +16 -0
  86. package/src/projection-uniform.ts +5 -1
  87. package/src/quiet-markers.ts +56 -0
  88. package/src/render/budget-ladder.ts +256 -0
  89. package/src/render/chain.ts +89 -7
  90. package/src/render/exposure-units.ts +59 -0
  91. package/src/render/frame-time-budget.ts +162 -0
  92. package/src/render/gi-budget.ts +231 -0
  93. package/src/render/gi-visualize.ts +49 -0
  94. package/src/render/material-key.ts +1 -0
  95. package/src/render/probe-volume.ts +196 -36
  96. package/src/render/rough-diffuse.ts +177 -0
  97. package/src/render/scene-trace.ts +532 -0
  98. package/src/render/shadow-filter-budget.ts +237 -0
  99. package/src/render/sky-capture.ts +194 -0
  100. package/src/render/soft-shadow.ts +607 -0
  101. package/src/render/surface-cache.ts +418 -0
  102. package/src/render/traced-reflections.ts +408 -0
  103. package/src/render/two-sided-foliage.ts +120 -0
  104. package/src/render/virtual-shadow-pages.ts +112 -12
  105. package/src/render/virtual-shadow.ts +386 -38
  106. package/src/render-camera-cull.ts +536 -31
  107. package/src/render-pass-budget.ts +140 -22
  108. package/src/renderProjection.ts +65 -9
  109. package/src/renderer-config.ts +3 -2
  110. package/src/renderer.ts +289 -14
  111. package/src/resolution-scaler.ts +65 -7
  112. package/src/skeletal-mesh.ts +4 -0
  113. package/src/snow-field.ts +46 -0
  114. package/src/softbody.ts +6 -5
  115. package/src/startup-offscreen-bytes.ts +168 -0
  116. package/src/startup-readiness.ts +137 -2
  117. package/src/ui-bridge.ts +38 -0
  118. package/src/ui-hit-regions.ts +6 -2
  119. package/src/ui-layer.ts +1 -0
  120. package/src/ui-state.ts +32 -3
  121. package/src/version.ts +1 -1
  122. package/src/viewport.ts +8 -5
  123. package/src/warmup.ts +76 -10
  124. package/src/worker-audio.ts +579 -0
  125. package/src/worker.ts +842 -0
  126. package/src/world-cells.ts +4 -1
  127. package/gpl/LICENSE.GPL +0 -117
  128. package/gpl/convert.py +0 -192
  129. package/gpl/fixtures/make_world_fixture.py +0 -184
  130. package/gpl/recipes/_common.py +0 -180
  131. package/gpl/recipes/bake_ao.py +0 -111
  132. package/gpl/recipes/decimate.py +0 -70
  133. package/gpl/recipes/export_world.py +0 -699
  134. package/gpl/recipes/retarget.py +0 -131
  135. package/gpl/recipes/unwrap.py +0 -71
  136. package/mcp/blender-server.mjs +0 -689
  137. package/mcp/blender.mjs +0 -26
package/src/playtest.ts CHANGED
@@ -23,6 +23,7 @@ import type { EntitySnapshot } from "./entities.js";
23
23
  import type { IGameObservationContribution, IGamePluginHooks, IGamePluginRuntime } from "./game.js";
24
24
  import { GEOMETRY_CAPTURE_CAPABILITY } from "./geometry-capture.js";
25
25
  import { PIPELINE_CENSUS_CAPABILITY } from "./pipeline-census.js";
26
+ import { discardEngineCountsSinceLastFrame } from "./profiling/FrameCounters.js";
26
27
  import { readRenderChainObservation } from "./render/chain.js";
27
28
  import type { ICtx } from "./scene.js";
28
29
  import { CORE_VERSION } from "./version.js";
@@ -156,11 +157,21 @@ export function playtest<
156
157
  ...(runtime?.startupCompileSettled === undefined
157
158
  ? {}
158
159
  : { compileSettled: runtime.startupCompileSettled() }),
160
+ ...(runtime?.startupRevealed === undefined
161
+ ? {}
162
+ : { revealed: runtime.startupRevealed() }),
159
163
  // Wall-clock milestones, so a scenario asserts startup time as an observation instead
160
164
  // of reading it off a console marker after the fact.
161
165
  ...(runtime?.startupTimeline === undefined
162
166
  ? {}
163
167
  : { timeline: runtime.startupTimeline() }),
168
+ // What the reveal waited for that the spawn camera does not show, once the reveal ran.
169
+ ...((offscreen) =>
170
+ offscreen === undefined
171
+ ? {}
172
+ : {
173
+ offscreenBytes: { ...offscreen, top: offscreen.top.map((file) => ({ ...file })) },
174
+ })(runtime?.startupOffscreenBytes?.()),
164
175
  }),
165
176
  };
166
177
  const installation = installThreePlaytestBridge(bridgeOptions);
@@ -227,7 +238,12 @@ export function playtest<
227
238
  if (!wallClock) runtime?.freezeClock?.();
228
239
  }
229
240
  dispose = installation.dispose;
230
- attached = holdUntilAttached(installation.bridge, options, () => startSceneEntered);
241
+ attached = holdUntilAttached(
242
+ installation.bridge,
243
+ options,
244
+ () => startSceneEntered,
245
+ runtime?.startSceneLoaded,
246
+ );
231
247
  const cleanup = () => {
232
248
  if (!clockDisposed && clockRuntime?._setClockMode !== undefined)
233
249
  clockControl._setClockMode("fixed-step");
@@ -378,6 +394,7 @@ function holdUntilAttached(
378
394
  bridge: IPlaytestBridgeV1,
379
395
  options: IPlaytestOptions,
380
396
  startSceneEntered: () => Promise<void> | undefined,
397
+ startSceneLoaded?: () => Promise<void>,
381
398
  ): Promise<void> | undefined {
382
399
  if (!shouldHoldUntilAttached(options)) return undefined;
383
400
  const timeoutMs = options.attachTimeoutMs ?? PLAYTEST_ATTACH_TIMEOUT_MS;
@@ -413,6 +430,9 @@ function holdUntilAttached(
413
430
  if (applySetup !== undefined) {
414
431
  bridge.applySetup = async (request) => {
415
432
  try {
433
+ // Setup names entities the start scene's load() registers; an async load is still
434
+ // pending when the runner first attaches.
435
+ await startSceneLoaded?.();
416
436
  const confirmation = await applySetup(request);
417
437
  release();
418
438
  return confirmation;
@@ -451,9 +471,16 @@ function installRuntimeChannels(
451
471
  );
452
472
  const sample = bridge.sample;
453
473
  bridge.sample = (request) =>
454
- Promise.resolve(sample(request)).then((snapshot) =>
455
- addRuntimeObservations(snapshot, request, runtime?.observations.contributions() ?? []),
456
- );
474
+ Promise.resolve(sample(request)).then(async (snapshot) => {
475
+ const observed = await addRuntimeObservations(
476
+ snapshot,
477
+ request,
478
+ runtime?.observations.contributions() ?? [],
479
+ );
480
+ // An observation walks the scene for entity `debug()`; the next frame is not billed for it.
481
+ discardEngineCountsSinceLastFrame();
482
+ return observed;
483
+ });
457
484
  }
458
485
  function addRuntimeCapabilities(
459
486
  description: IPlaytestBridgeDescription,
@@ -518,9 +545,9 @@ function bridgeEntities<TState extends Record<string, unknown>, TPhysics>(
518
545
  }
519
546
  function entityObject(entity: object | undefined): ThreeObject3D | undefined {
520
547
  if (entity instanceof Object3D) return entity;
521
- const candidate =
522
- (entity as { mesh?: unknown; object?: unknown } | undefined)?.mesh ??
523
- (entity as { mesh?: unknown; object?: unknown } | undefined)?.object;
548
+ // A game's own entity class usually exposes its root as `mesh`, `object` or `group`.
549
+ const roots = entity as { group?: unknown; mesh?: unknown; object?: unknown } | undefined;
550
+ const candidate = roots?.mesh ?? roots?.object ?? roots?.group;
524
551
  return candidate instanceof Object3D ? candidate : undefined;
525
552
  }
526
553
  function gameplayObservations<TState extends Record<string, unknown>, TPhysics>(
@@ -599,6 +626,7 @@ function strideObservation(value: unknown): IPlaytestStrideObservation | undefin
599
626
  return {
600
627
  clipGroundSpeed: report.clipGroundSpeed as number,
601
628
  groundSpeed: report.groundSpeed as number,
629
+ ...(typeof report.inPlace === "boolean" ? { inPlace: report.inPlace } : {}),
602
630
  overridden: report.overridden as boolean,
603
631
  rate: report.rate as number,
604
632
  synced: report.synced as boolean,
@@ -760,7 +788,8 @@ function objectGraphValues(root: object | undefined): object[] {
760
788
  if (value === null || typeof value !== "object" || visited.has(value)) return;
761
789
  visited.add(value);
762
790
  values.push(value);
763
- if (depth >= 4 || value instanceof Object3D) return;
791
+ // Numeric storage is leaf data, not a container of contact adapters.
792
+ if (depth >= 4 || value instanceof Object3D || ArrayBuffer.isView(value)) return;
764
793
  for (const child of Object.values(value)) visit(child, depth + 1);
765
794
  };
766
795
  visit(root, 0);
@@ -808,6 +837,7 @@ function stateResources<TState extends Record<string, unknown>, TPhysics>(
808
837
  // Where every asset was actually served from, on every target and not only in a browser
809
838
  // console log: a game whose manifest never loaded runs on the uncompiled source directory
810
839
  // and looks healthy, and without this nothing observable says so.
840
+ ["assetCache", assetCacheReport(ctx.assets)],
811
841
  ["assets", assetResolutions(ctx.assets)],
812
842
  ...(runtime?.frameCounts === undefined
813
843
  ? []
@@ -817,6 +847,22 @@ function stateResources<TState extends Record<string, unknown>, TPhysics>(
817
847
  };
818
848
  }
819
849
 
850
+ /** The cache counters and switches, without the action; observations are data. */
851
+ function assetCacheReport(assets: IAssetLoader): Record<string, JsonValue> {
852
+ const cache = assets.cache;
853
+ return {
854
+ enabled: cache.enabled,
855
+ persisted: cache.persisted,
856
+ hits: cache.hits,
857
+ misses: cache.misses,
858
+ bytesOnDisk: cache.bytesOnDisk,
859
+ bytesTotal: cache.bytesTotal,
860
+ filling: cache.filling,
861
+ backgroundFill: cache.backgroundFill,
862
+ ...(cache.reason === undefined ? {} : { reason: cache.reason }),
863
+ };
864
+ }
865
+
820
866
  /**
821
867
  * The asset loader's `resolved` ledger, nested on the dots of each logical path.
822
868
  *
@@ -1,3 +1,5 @@
1
+ import { countDebug, debugRequested, isContentScaled } from "./debug-telemetry.js";
2
+
1
3
  /**
2
4
  * Host-boundary counters, default-off, on the frame budget's own record.
3
5
  *
@@ -35,6 +37,21 @@ export interface IFrameCounters {
35
37
  readonly gpuBytes?: number;
36
38
  readonly hostCalls?: number;
37
39
  readonly jsAllocBytes?: number;
40
+ /**
41
+ * JS->Wasm crossings this frame, from the web back end's own count (`createCrossingReader`).
42
+ * Absent on a host whose back end keeps no such count.
43
+ */
44
+ readonly bridgeCrossings?: number;
45
+ /** Transforms the game moved this frame (the owned engine's `markLocalTransformDirty` calls; PRD-771). */
46
+ readonly dirtyTransforms?: number;
47
+ /** Shadow casters the virtual atlas judged moving this frame, each one invalidating its pages (PRD-771). */
48
+ readonly castersMoving?: number;
49
+ /**
50
+ * This frame's engine work counts by name (`createEngineCounterReader`): the web back end's and the
51
+ * engine's own totals, and `globalThis.__tnEngineCost`, differenced per frame. Absent unless a
52
+ * playtest asked for them.
53
+ */
54
+ readonly engine?: Readonly<Record<string, number>>;
38
55
  /** The loop's fixed-step count at the frame's end; absent when the caller did not feed one. */
39
56
  readonly simulationTick?: number;
40
57
  }
@@ -58,6 +75,18 @@ const SKIP: Record<string, true> = {
58
75
  removeEventListener: true,
59
76
  };
60
77
 
78
+ const GPU_COUNTERS: Readonly<Record<string, string>> = {
79
+ createBuffer: "gpuBufferCreates",
80
+ createTexture: "gpuTextureCreates",
81
+ createBindGroup: "gpuBindGroupCreates",
82
+ createRenderPipeline: "gpuPipelineCompiles",
83
+ createRenderPipelineAsync: "gpuPipelineCompiles",
84
+ mapAsync: "gpuReadbackMaps",
85
+ submit: "gpuQueueSubmits",
86
+ resolveQuerySet: "gpuQueryResolves",
87
+ beginRenderPass: "gpuRenderPasses",
88
+ };
89
+
61
90
  /**
62
91
  * Every function-valued method name on an object and its prototype chain.
63
92
  *
@@ -116,6 +145,7 @@ export function counterDeviceOf(raw: unknown): unknown {
116
145
  * allocation. Install once per renderer; `read` returns the counts since the previous `read`.
117
146
  */
118
147
  export class FrameCounters {
148
+ readonly #debug = debugRequested();
119
149
  #hostCalls = 0;
120
150
  #gpuBytes = 0;
121
151
  #lastHeapBytes: number | undefined;
@@ -125,9 +155,15 @@ export class FrameCounters {
125
155
  private constructor(device: ICounterDevice) {
126
156
  // A new encoder per pass, so an encoder's methods are wrapped the first time it is seen rather
127
157
  // than once at install: a wrapper installed on one encoder would miss every later pass.
128
- this.#wrap(device, ["createCommandEncoder", "createRenderBundleEncoder"], (_name, result) => {
129
- if (typeof result === "object" && result !== null) this.#wrapEncoder(result);
130
- });
158
+ this.#wrap(
159
+ device,
160
+ this.#debug ? methodNames(device) : ["createCommandEncoder", "createRenderBundleEncoder"],
161
+ (name, result) => {
162
+ if (typeof result !== "object" || result === null) return;
163
+ if (name.endsWith("Encoder")) this.#wrapEncoder(result);
164
+ if (this.#debug && name === "createBuffer") this.#wrap(result, ["mapAsync"], undefined);
165
+ },
166
+ );
131
167
  const queue = device.queue;
132
168
  if (typeof queue === "object" && queue !== null)
133
169
  this.#wrap(queue, methodNames(queue), undefined);
@@ -160,6 +196,7 @@ export class FrameCounters {
160
196
  if (original === undefined) continue;
161
197
  const wrapped = (...args: unknown[]): unknown => {
162
198
  this.#hostCalls += 1;
199
+ const start = this.#debug ? performance.now() : undefined;
163
200
  if (name === "writeBuffer") {
164
201
  // `writeBuffer(buffer, offset, data, dataOffset, size)`; `size` defaults to the rest of
165
202
  // the source, exactly as the spec says, so the count matches the bytes the driver sees.
@@ -173,16 +210,33 @@ export class FrameCounters {
173
210
  typeof data.byteLength === "number"
174
211
  ? data.byteLength
175
212
  : 0;
176
- this.#gpuBytes += size ?? Math.max(0, available - dataOffset);
213
+ const elementBytes =
214
+ ArrayBuffer.isView(data) &&
215
+ "BYTES_PER_ELEMENT" in data &&
216
+ typeof data.BYTES_PER_ELEMENT === "number"
217
+ ? data.BYTES_PER_ELEMENT
218
+ : 1;
219
+ this.#gpuBytes +=
220
+ size === undefined
221
+ ? Math.max(0, available - dataOffset * elementBytes)
222
+ : size * elementBytes;
177
223
  }
178
224
  const result = original.apply(owner, args);
225
+ if (this.#debug) {
226
+ const field = GPU_COUNTERS[name];
227
+ if (field !== undefined) countDebug(field, 1, "gpu", `WebGPU.${name}`);
228
+ if (start !== undefined)
229
+ countDebug(`gpu.${name}Ms`, performance.now() - start, "gpu", `WebGPU.${name}`, "ms");
230
+ }
179
231
  after?.(name, result);
180
232
  return result;
181
233
  };
182
234
  try {
183
235
  target[name] = wrapped;
236
+ const weak = new WeakRef(target);
184
237
  this.#restore.push(() => {
185
- target[name] = original;
238
+ const live = weak.deref();
239
+ if (live !== undefined) live[name] = original;
186
240
  });
187
241
  } catch {
188
242
  // A native binding may expose a non-writable method. Losing that one from the count is a
@@ -204,6 +258,16 @@ export class FrameCounters {
204
258
  if (heap !== undefined) {
205
259
  const previous = this.#lastHeapBytes;
206
260
  this.#lastHeapBytes = heap;
261
+ if (this.#debug) {
262
+ countDebug("jsHeapBytesSampled", heap, "memory", "performance.memory.usedJSHeapSize");
263
+ if (previous !== undefined)
264
+ countDebug(
265
+ heap >= previous ? "jsHeapGrowthBytes" : "jsHeapShrinkBytes",
266
+ Math.abs(heap - previous),
267
+ "memory",
268
+ "performance.memory.usedJSHeapSize",
269
+ );
270
+ }
207
271
  if (previous !== undefined && heap >= previous)
208
272
  return { ...counters, jsAllocBytes: heap - previous };
209
273
  return counters;
@@ -229,3 +293,100 @@ function readHeapBytes(): number | undefined {
229
293
  const used = perf?.memory?.usedJSHeapSize;
230
294
  return typeof used === "number" && Number.isFinite(used) ? used : undefined;
231
295
  }
296
+
297
+ /**
298
+ * The web back end's running count of JS->Wasm crossings, when the engine publishes one.
299
+ *
300
+ * `@threenative/three-native` installs `globalThis.__tnCrossingCount` (browser-entry.ts) and answers
301
+ * the total so far, so one frame's crossings are a difference of two reads. It is a different number
302
+ * from `hostCalls`: this counts the game's and the engine's calls into the engine's own ABI, which
303
+ * on the owned engine is a Wasm boundary on the game thread, and `hostCalls` counts WebGPU API calls.
304
+ * A host with no such back end (upstream three, the native player) answers `undefined`, and the
305
+ * field stays absent rather than reading zero.
306
+ *
307
+ * Per frame, not cumulative: the counter rides the frame budget's window, whose series are
308
+ * per-frame samples, and a cumulative total would climb with the window and say nothing about a frame.
309
+ */
310
+ /** Set to `true` by a playtest that bounds engine counters (`engineCost`); three-native reads the same name. */
311
+ export const ENGINE_COST_KNOB = "__THREENATIVE_ENGINE_COST__";
312
+
313
+ interface IEngineCounterHost {
314
+ readonly __tnDebugSources?: Readonly<Record<string, { readonly unit?: string }>>;
315
+ readonly __THREENATIVE_ENGINE_COST__?: unknown;
316
+ /** The web back end's running totals by name (three-native browser-entry.ts). */
317
+ readonly __tnEngineCounters?: () => Readonly<Record<string, number>>;
318
+ /** Totals any module counts by name (`bag[name] = (bag[name] ?? 0) + 1`), on every engine. */
319
+ readonly __tnEngineCost?: Readonly<Record<string, number>>;
320
+ /** Installed by the reader while it is on: drops the counts since the last frame's read. */
321
+ __tnEngineCounterRebase?: () => void;
322
+ }
323
+
324
+ /**
325
+ * Leaves the work done since the last frame out of the next frame's engine counts. A caller that does
326
+ * work between frames which is not the game's (the playtest bridge answering an observation walks the
327
+ * scene for `debug()`) calls this when it is done; without it the next frame is billed for the walk
328
+ * and a bound on one frame's cost fails on a measurement of the harness, on a timing race.
329
+ */
330
+ export function discardEngineCountsSinceLastFrame(
331
+ host: Pick<IEngineCounterHost, "__tnEngineCounterRebase"> = globalThis as IEngineCounterHost,
332
+ ): void {
333
+ host.__tnEngineCounterRebase?.();
334
+ }
335
+
336
+ /**
337
+ * One reader for every engine work counter, so a playtest bounds them all from one surface,
338
+ * `TN_FRAME_BUDGET.counters.engine` (PRD-748's engine-cost row). Each source answers running totals;
339
+ * this answers one frame's difference per name. Off unless `ENGINE_COST_KNOB` is set, so a shipped
340
+ * frame pays nothing; the first read of a run is the baseline, not a frame.
341
+ */
342
+ export function createEngineCounterReader(
343
+ host: IEngineCounterHost = globalThis as IEngineCounterHost,
344
+ ): () => Record<string, number> | undefined {
345
+ const debug = debugRequested();
346
+ let last: Record<string, number> | undefined;
347
+ const read = (): Record<string, number> => ({
348
+ ...host.__tnEngineCost,
349
+ ...host.__tnEngineCounters?.(),
350
+ });
351
+ return () => {
352
+ if (!debug && host.__THREENATIVE_ENGINE_COST__ !== true) return undefined;
353
+ host.__tnEngineCounterRebase ??= () => {
354
+ if (last !== undefined) last = read();
355
+ };
356
+ const totals = read();
357
+ const previous = last;
358
+ last = totals;
359
+ if (previous === undefined) return undefined;
360
+ const frame: Record<string, number> = {};
361
+ // A name first counted this frame started from zero after the baseline.
362
+ for (const [name, total] of Object.entries(totals)) {
363
+ if (!Number.isFinite(total) || total < 0)
364
+ throw new Error(`TN_DEBUG: invalid ${name} counter.`);
365
+ // One name per asset URL or bridged property would add a ring per item the scene loads; the
366
+ // report ranks the run's largest ten of them instead (`isContentScaled`).
367
+ if (isContentScaled(name)) continue;
368
+ frame[name] =
369
+ debug && host.__tnDebugSources?.[name]?.unit === "gauge"
370
+ ? total
371
+ : Math.max(0, total - (previous[name] ?? 0));
372
+ }
373
+ return frame;
374
+ };
375
+ }
376
+
377
+ export function createCrossingReader(
378
+ host: { readonly __tnCrossingCount?: () => number } = globalThis as {
379
+ readonly __tnCrossingCount?: () => number;
380
+ },
381
+ ): () => number | undefined {
382
+ let last: number | undefined;
383
+ return () => {
384
+ if (typeof host.__tnCrossingCount !== "function") return undefined;
385
+ const total = host.__tnCrossingCount();
386
+ if (!Number.isFinite(total)) return undefined;
387
+ const previous = last;
388
+ last = total;
389
+ // The first read of a run is not a frame's worth of crossings: it is everything since boot.
390
+ return previous === undefined ? undefined : Math.max(0, total - previous);
391
+ };
392
+ }
@@ -0,0 +1,289 @@
1
+ /**
2
+ * Where the main-thread frame goes, by stage (PRD-771).
3
+ *
4
+ * The frame budget's `render` phase wraps one synchronous `renderer.render()` call, and on the owned
5
+ * Wasm engine that call holds the scene walk, the draw plan, the encode, the post passes and the queue
6
+ * submit, all in C++. A phase that large with nothing named inside it is a question, not a measurement.
7
+ * This splits it with one clock read per boundary, so the split rides every window rather than a
8
+ * diagnostic flag:
9
+ *
10
+ * - the JS before the engine call (cull, `beforeRender`, reconcile, LOD, matrix walk) and after it;
11
+ * - the engine's own CPU stages, from the running totals the Wasm facade publishes in
12
+ * `renderer.info.engine.cpuMs` (three-native `gpu-stages.ts`), differenced per frame;
13
+ * - what is left of the call, named: JS inside `render()` around the Wasm call, and Wasm time no stage owns.
14
+ *
15
+ * The stages partition the render phase. `wasmOther` and `engineJs` are subtractions, published as
16
+ * stages (`wasmRendererGap` is what `Renderer::render` spends outside its plan and encode halves) so the unlocated time is a number and never a quiet category. On an engine that publishes no
17
+ * stage totals (upstream three), the whole call is `engineJs`.
18
+ */
19
+
20
+ import type { IFrameCounters } from "./FrameCounters.js";
21
+
22
+ /** The stages of the render phase, in the order a frame spends them. They sum to the frame's `render` phase. */
23
+ export const RENDER_STAGES = [
24
+ "jsBefore",
25
+ "engineJs",
26
+ "wasmScene",
27
+ "wasmPlan",
28
+ "wasmCompute",
29
+ "wasmEncode",
30
+ "wasmPost",
31
+ "wasmSubmit",
32
+ "wasmPoll",
33
+ "wasmTail",
34
+ "wasmRendererGap",
35
+ "wasmDatabaseGap",
36
+ "wasmTargets",
37
+ "wasmOther",
38
+ "jsAfter",
39
+ ] as const;
40
+
41
+ export type RenderStage = (typeof RENDER_STAGES)[number];
42
+
43
+ /**
44
+ * Parts of a stage, published beside it and never added to the sum: `wasmPlan` holds all three, in the order the
45
+ * renderer runs them, and what is left of it is the rest of the prepare half.
46
+ */
47
+ export const STAGE_PARTS = ["planVirtualPages", "planDraws", "planShadowLists"] as const;
48
+
49
+ export type StagePart = (typeof STAGE_PARTS)[number];
50
+
51
+ /** One frame's stages in milliseconds, reused across frames so the read allocates nothing. */
52
+ export type IFrameStageSample = Record<RenderStage | StagePart, number | undefined>;
53
+
54
+ /** The running totals the Wasm facade publishes (`renderer.info.engine.cpuMs`), in ms. */
55
+ export interface IEngineCpuTotals {
56
+ readonly cpuVirtualPagesMs: number;
57
+ readonly cpuPlanMs: number;
58
+ readonly cpuShadowBuildMs: number;
59
+ readonly cpuPrepareMs: number;
60
+ readonly cpuEncodeMs: number;
61
+ readonly cpuPostMs: number;
62
+ readonly cpuSceneMs: number;
63
+ readonly hostRenderMs: number;
64
+ readonly hostComputeMs: number;
65
+ readonly hostSubmitMs: number;
66
+ readonly hostPollMs: number;
67
+ readonly hostTailMs: number;
68
+ readonly rendererMs: number;
69
+ readonly hostDatabaseMs: number;
70
+ readonly hostTargetMs: number;
71
+ }
72
+
73
+ const TOTAL_NAMES = [
74
+ "cpuVirtualPagesMs",
75
+ "cpuPlanMs",
76
+ "cpuShadowBuildMs",
77
+ "cpuPrepareMs",
78
+ "cpuEncodeMs",
79
+ "cpuPostMs",
80
+ "cpuSceneMs",
81
+ "hostRenderMs",
82
+ "hostComputeMs",
83
+ "hostSubmitMs",
84
+ "hostPollMs",
85
+ "hostTailMs",
86
+ "rendererMs",
87
+ "hostDatabaseMs",
88
+ "hostTargetMs",
89
+ ] as const satisfies readonly (keyof IEngineCpuTotals)[];
90
+
91
+ /** A fresh sample with every stage at zero. */
92
+ export function emptyStageSample(): IFrameStageSample {
93
+ return {
94
+ engineJs: 0,
95
+ jsAfter: 0,
96
+ jsBefore: 0,
97
+ planDraws: 0,
98
+ planShadowLists: 0,
99
+ planVirtualPages: 0,
100
+ wasmCompute: 0,
101
+ wasmDatabaseGap: 0,
102
+ wasmEncode: 0,
103
+ wasmOther: 0,
104
+ wasmPlan: 0,
105
+ wasmPoll: 0,
106
+ wasmPost: 0,
107
+ wasmRendererGap: 0,
108
+ wasmScene: 0,
109
+ wasmSubmit: 0,
110
+ wasmTail: 0,
111
+ wasmTargets: 0,
112
+ };
113
+ }
114
+
115
+ /** Every stage and part that only the engine's totals can fill. */
116
+ const UNMEASURED_WITHOUT_TOTALS = [
117
+ "wasmScene",
118
+ "wasmPlan",
119
+ "wasmCompute",
120
+ "wasmEncode",
121
+ "wasmPost",
122
+ "wasmSubmit",
123
+ "wasmPoll",
124
+ "wasmTail",
125
+ "wasmRendererGap",
126
+ "wasmDatabaseGap",
127
+ "wasmTargets",
128
+ "wasmOther",
129
+ "planVirtualPages",
130
+ "planDraws",
131
+ "planShadowLists",
132
+ ] as const;
133
+
134
+ const positive = (value: number): number => (value > 0 ? value : 0);
135
+
136
+ interface IEngineCpuHost {
137
+ readonly info?: { readonly engine?: { readonly cpuMs?: Partial<IEngineCpuTotals> } };
138
+ }
139
+
140
+ /**
141
+ * The reader `game.ts` calls once per rendered frame with the three JS timings of that frame. It returns the
142
+ * frame's stages (the same object every call) or `undefined` for the baseline read, so a run's first frame
143
+ * is not charged everything since boot.
144
+ *
145
+ * `renderer` is the raw renderer; one that publishes no stage totals gets the whole call as `engineJs`.
146
+ * Wasm time is wall time on the page's clock; the totals only ever grow, so a negative difference (a
147
+ * restarted engine) reads as zero rather than a negative stage.
148
+ */
149
+ export function createStageReader(
150
+ renderer: () => unknown,
151
+ ): (jsBefore: number, engineCall: number, jsAfter: number) => IFrameStageSample | undefined {
152
+ const sample = emptyStageSample();
153
+ const last = new Float64Array(TOTAL_NAMES.length);
154
+ let haveLast = false;
155
+ return (jsBefore, engineCall, jsAfter) => {
156
+ sample.jsBefore = positive(jsBefore);
157
+ sample.jsAfter = positive(jsAfter);
158
+ const totals = (renderer() as IEngineCpuHost | null | undefined)?.info?.engine?.cpuMs;
159
+ if (totals === undefined) {
160
+ // A stage the engine did not measure is absent, never zero: the window leaves it out and the sum skips it.
161
+ sample.engineJs = positive(engineCall);
162
+ for (const name of UNMEASURED_WITHOUT_TOTALS) sample[name] = undefined;
163
+ return sample;
164
+ }
165
+ let delta0 = 0;
166
+ const delta = (index: number): number => {
167
+ const total = totals[TOTAL_NAMES[index] as keyof IEngineCpuTotals] ?? 0;
168
+ const previous = last[index] ?? 0;
169
+ last[index] = total;
170
+ delta0 = positive(total - previous);
171
+ return delta0;
172
+ };
173
+ const virtualPages = delta(0);
174
+ const draws = delta(1);
175
+ const shadowLists = delta(2);
176
+ const prepare = delta(3);
177
+ const encode = delta(4);
178
+ const post = delta(5);
179
+ const scene = delta(6);
180
+ const host = delta(7);
181
+ const compute = delta(8);
182
+ const submit = delta(9);
183
+ const poll = delta(10);
184
+ const tail = delta(11);
185
+ const inRenderer = delta(12);
186
+ const inDatabase = delta(13);
187
+ const targets = delta(14);
188
+ if (!haveLast) {
189
+ haveLast = true;
190
+ return undefined;
191
+ }
192
+ const encodeOnly = positive(encode - post);
193
+ sample.wasmScene = scene;
194
+ sample.wasmPlan = prepare;
195
+ sample.wasmCompute = compute;
196
+ sample.wasmEncode = encodeOnly;
197
+ sample.wasmPost = post;
198
+ sample.wasmSubmit = submit;
199
+ sample.wasmPoll = poll;
200
+ sample.wasmTail = tail;
201
+ sample.wasmRendererGap = positive(inRenderer - prepare - encode);
202
+ sample.wasmDatabaseGap = positive(inDatabase - scene - inRenderer);
203
+ sample.wasmTargets = targets;
204
+ sample.planVirtualPages = virtualPages;
205
+ sample.planDraws = draws;
206
+ sample.planShadowLists = shadowLists;
207
+ sample.wasmOther = positive(host - (inDatabase + targets + compute + submit + poll + tail));
208
+ sample.engineJs = positive(engineCall - host);
209
+ return sample;
210
+ };
211
+ }
212
+
213
+ /**
214
+ * Whether this launch reads the stage meters. On unless the launch turns them off: `?tnStages=0` in the URL,
215
+ * `TN_STAGES=0` in a native host's environment, or `globalThis.__tnStages = false` before the game boots.
216
+ * Off, the frame reads no extra clock, the engine reads none around its stages, and the window carries no
217
+ * `stages`: the paired A/B that prices the meters runs one build with this switch alone.
218
+ */
219
+ export function stageMetersRequested(): boolean {
220
+ const host = globalThis as { process?: { env?: Record<string, unknown> }; __tnStages?: unknown };
221
+ const fromEnv = host.process?.env?.TN_STAGES;
222
+ if (fromEnv === "0" || fromEnv === "false") return false;
223
+ const query = globalThis.location?.search;
224
+ if (typeof query === "string" && /[?&]tnStages=(?:0|false)(?:&|$)/u.test(query)) return false;
225
+ return host.__tnStages !== false;
226
+ }
227
+
228
+ interface IEngineWorkHost {
229
+ readonly info?: {
230
+ readonly engine?: {
231
+ readonly work?: {
232
+ readonly dirtyTransforms?: number;
233
+ readonly castersMoving?: number;
234
+ readonly queueWriteBytes?: number;
235
+ };
236
+ };
237
+ };
238
+ }
239
+
240
+ /**
241
+ * The frame's work counts beside its stages (PRD-771), as `IFrameCounters` fields: transforms moved, shadow
242
+ * casters judged moving, bytes the GPU queue took (`gpuBytes`, buffer writes only), the engine ABI calls
243
+ * (`hostCalls`, which on the owned engine are the bridge crossings the caller passes in) and the JS heap the
244
+ * frame grew (`jsAllocBytes`, from `performance.memory`; a frame the collector ran in reads 0, so it is a floor).
245
+ * The first read is the baseline. A count the engine does not publish stays absent, never zero.
246
+ */
247
+ export function createWorkReader(
248
+ renderer: () => unknown,
249
+ ): (
250
+ crossings: number | undefined,
251
+ ) =>
252
+ | Pick<
253
+ IFrameCounters,
254
+ "castersMoving" | "dirtyTransforms" | "gpuBytes" | "hostCalls" | "jsAllocBytes"
255
+ >
256
+ | undefined {
257
+ let last: { dirty: number; moving: number; bytes: number } | undefined;
258
+ let heap: number | undefined;
259
+ return (crossings) => {
260
+ const work = (renderer() as IEngineWorkHost | null | undefined)?.info?.engine?.work;
261
+ const memory = (globalThis.performance as { memory?: { usedJSHeapSize?: unknown } } | undefined)
262
+ ?.memory?.usedJSHeapSize;
263
+ const used = typeof memory === "number" && Number.isFinite(memory) ? memory : undefined;
264
+ const grown = used === undefined || heap === undefined ? undefined : positive(used - heap);
265
+ heap = used;
266
+ if (
267
+ work === undefined ||
268
+ typeof work.dirtyTransforms !== "number" ||
269
+ typeof work.castersMoving !== "number" ||
270
+ typeof work.queueWriteBytes !== "number"
271
+ )
272
+ return undefined;
273
+ const now = {
274
+ dirty: work.dirtyTransforms,
275
+ moving: work.castersMoving,
276
+ bytes: work.queueWriteBytes,
277
+ };
278
+ const previous = last;
279
+ last = now;
280
+ if (previous === undefined) return undefined;
281
+ return {
282
+ castersMoving: positive(now.moving - previous.moving),
283
+ dirtyTransforms: positive(now.dirty - previous.dirty),
284
+ gpuBytes: positive(now.bytes - previous.bytes),
285
+ ...(crossings === undefined ? {} : { hostCalls: crossings }),
286
+ ...(grown === undefined ? {} : { jsAllocBytes: grown }),
287
+ };
288
+ };
289
+ }