@threenative/core 0.3.5 → 0.3.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/README.md +3 -5
  2. package/capabilities.json +739 -50
  3. package/dist/{assets-CqvE429w.d.ts → assets-YUbXa3-Y.d.ts} +101 -2
  4. package/dist/{canvas-layer-C1-5CviZ.d.ts → canvas-layer-vCtanIeB.d.ts} +1 -1
  5. package/dist/{game-Bj8G1wmD.d.ts → game-cb99J-YE.d.ts} +112 -31
  6. package/dist/hot.d.ts +4 -4
  7. package/dist/hot.js +23 -5
  8. package/dist/index.d.ts +1742 -29
  9. package/dist/index.js +22445 -12411
  10. package/dist/{model-lod-BDAUYgsS.d.ts → model-lod-CTpZ6imz.d.ts} +1 -1
  11. package/dist/net.js +39 -12
  12. package/dist/playtest.d.ts +4 -4
  13. package/dist/playtest.js +59 -10
  14. package/dist/react-css.js +23 -0
  15. package/dist/react.d.ts +2 -2
  16. package/dist/{renderer-9yEo9hPa.d.ts → renderer-rZm0hVqq.d.ts} +178 -5
  17. package/dist/ui-layer.d.ts +11 -2
  18. package/dist/ui-layer.js +76 -4
  19. package/dist/worker.d.ts +36 -0
  20. package/dist/worker.js +1088 -0
  21. package/dist/world.d.ts +11 -3
  22. package/dist/world.js +1117 -197
  23. package/mcp/animation-server.mjs +265 -0
  24. package/mcp/animation.mjs +22 -0
  25. package/mcp/call.mjs +105 -0
  26. package/mcp/devtools.mjs +5 -0
  27. package/mcp/engine-server.mjs +713 -37
  28. package/mcp/launch.mjs +3 -2
  29. package/mcp/servers.d.mts +2 -0
  30. package/mcp/servers.mjs +33 -8
  31. package/package.json +12 -8
  32. package/patches/three@0.185.1-prd269-upgrade.patch +308 -0
  33. package/patches/three@0.185.1.patch +481 -272
  34. package/src/animation-packet-state.ts +88 -0
  35. package/src/animation-pose-packet.ts +537 -0
  36. package/src/animation.ts +779 -31
  37. package/src/asset-cache.ts +719 -0
  38. package/src/assets.ts +521 -152
  39. package/src/audio.ts +29 -3
  40. package/src/auto-batch.ts +792 -0
  41. package/src/config.ts +2 -0
  42. package/src/frame-budget.ts +268 -2
  43. package/src/game.ts +544 -106
  44. package/src/grounding.ts +7 -6
  45. package/src/hot.ts +19 -5
  46. package/src/index.ts +381 -6
  47. package/src/input.ts +21 -2
  48. package/src/interpolation.ts +19 -1
  49. package/src/launch-diagnostics.ts +7 -2
  50. package/src/look/ao-multibounce.ts +29 -0
  51. package/src/look/ao-reach.ts +39 -0
  52. package/src/look/auto-exposure.ts +264 -0
  53. package/src/look/default-tone-mapping.ts +44 -0
  54. package/src/look/exposure-graph.ts +208 -0
  55. package/src/look/exposure-readback.ts +97 -0
  56. package/src/look/exposure-settings.ts +132 -0
  57. package/src/look/filmic-tone-mapping.ts +852 -0
  58. package/src/look/gi-registry.ts +55 -0
  59. package/src/look/local-exposure.ts +507 -0
  60. package/src/look/look-diagnostics.ts +24 -0
  61. package/src/look/motion-blur.ts +42 -0
  62. package/src/look/quality.ts +309 -0
  63. package/src/look/reflection-trace.ts +344 -0
  64. package/src/look/unreal-bloom.ts +295 -0
  65. package/src/look/vignette.ts +14 -0
  66. package/src/look/world-environment.ts +2033 -0
  67. package/src/loop.ts +40 -6
  68. package/src/merge-parts.ts +25 -10
  69. package/src/model-lod.ts +14 -0
  70. package/src/net-session.ts +58 -14
  71. package/src/ocean/spectral.ts +41 -7
  72. package/src/picking.ts +72 -5
  73. package/src/platform.ts +29 -1
  74. package/src/playtest.ts +69 -12
  75. package/src/profiling/FrameCounters.ts +166 -5
  76. package/src/profiling/FrameStages.ts +289 -0
  77. package/src/profiling/Spans.ts +39 -25
  78. package/src/profiling/debug-telemetry.ts +312 -0
  79. package/src/profiling/scene-warning.ts +42 -6
  80. package/src/projection-apply.ts +11 -3
  81. package/src/projection-content.ts +189 -0
  82. package/src/projection-marker.ts +6 -2
  83. package/src/projection-plan.ts +279 -28
  84. package/src/projection-skinned.ts +620 -5
  85. package/src/projection-stability.ts +16 -0
  86. package/src/projection-uniform.ts +5 -1
  87. package/src/quiet-markers.ts +56 -0
  88. package/src/render/budget-ladder.ts +256 -0
  89. package/src/render/chain.ts +89 -7
  90. package/src/render/exposure-units.ts +59 -0
  91. package/src/render/frame-time-budget.ts +162 -0
  92. package/src/render/gi-budget.ts +231 -0
  93. package/src/render/gi-visualize.ts +49 -0
  94. package/src/render/material-key.ts +1 -0
  95. package/src/render/probe-volume.ts +196 -36
  96. package/src/render/rough-diffuse.ts +177 -0
  97. package/src/render/scene-trace.ts +532 -0
  98. package/src/render/shadow-filter-budget.ts +237 -0
  99. package/src/render/sky-capture.ts +194 -0
  100. package/src/render/soft-shadow.ts +607 -0
  101. package/src/render/surface-cache.ts +418 -0
  102. package/src/render/traced-reflections.ts +408 -0
  103. package/src/render/two-sided-foliage.ts +120 -0
  104. package/src/render/virtual-shadow-pages.ts +112 -12
  105. package/src/render/virtual-shadow.ts +386 -38
  106. package/src/render-camera-cull.ts +536 -31
  107. package/src/render-pass-budget.ts +140 -22
  108. package/src/renderProjection.ts +65 -9
  109. package/src/renderer-config.ts +3 -2
  110. package/src/renderer.ts +289 -14
  111. package/src/resolution-scaler.ts +65 -7
  112. package/src/skeletal-mesh.ts +4 -0
  113. package/src/snow-field.ts +46 -0
  114. package/src/softbody.ts +6 -5
  115. package/src/startup-offscreen-bytes.ts +168 -0
  116. package/src/startup-readiness.ts +137 -2
  117. package/src/ui-bridge.ts +38 -0
  118. package/src/ui-hit-regions.ts +6 -2
  119. package/src/ui-layer.ts +1 -0
  120. package/src/ui-state.ts +32 -3
  121. package/src/version.ts +1 -1
  122. package/src/viewport.ts +8 -5
  123. package/src/warmup.ts +76 -10
  124. package/src/worker-audio.ts +579 -0
  125. package/src/worker.ts +842 -0
  126. package/src/world-cells.ts +4 -1
  127. package/gpl/LICENSE.GPL +0 -117
  128. package/gpl/convert.py +0 -192
  129. package/gpl/fixtures/make_world_fixture.py +0 -184
  130. package/gpl/recipes/_common.py +0 -180
  131. package/gpl/recipes/bake_ao.py +0 -111
  132. package/gpl/recipes/decimate.py +0 -70
  133. package/gpl/recipes/export_world.py +0 -699
  134. package/gpl/recipes/retarget.py +0 -131
  135. package/gpl/recipes/unwrap.py +0 -71
  136. package/mcp/blender-server.mjs +0 -689
  137. package/mcp/blender.mjs +0 -26
@@ -37,6 +37,21 @@ interface IFrameCounters {
37
37
  readonly gpuBytes?: number;
38
38
  readonly hostCalls?: number;
39
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>>;
40
55
  /** The loop's fixed-step count at the frame's end; absent when the caller did not feed one. */
41
56
  readonly simulationTick?: number;
42
57
  }
@@ -63,6 +78,37 @@ declare class FrameCounters {
63
78
  uninstall(): void;
64
79
  }
65
80
 
81
+ /**
82
+ * Where the main-thread frame goes, by stage (PRD-771).
83
+ *
84
+ * The frame budget's `render` phase wraps one synchronous `renderer.render()` call, and on the owned
85
+ * Wasm engine that call holds the scene walk, the draw plan, the encode, the post passes and the queue
86
+ * submit, all in C++. A phase that large with nothing named inside it is a question, not a measurement.
87
+ * This splits it with one clock read per boundary, so the split rides every window rather than a
88
+ * diagnostic flag:
89
+ *
90
+ * - the JS before the engine call (cull, `beforeRender`, reconcile, LOD, matrix walk) and after it;
91
+ * - the engine's own CPU stages, from the running totals the Wasm facade publishes in
92
+ * `renderer.info.engine.cpuMs` (three-native `gpu-stages.ts`), differenced per frame;
93
+ * - what is left of the call, named: JS inside `render()` around the Wasm call, and Wasm time no stage owns.
94
+ *
95
+ * The stages partition the render phase. `wasmOther` and `engineJs` are subtractions, published as
96
+ * 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
97
+ * stage totals (upstream three), the whole call is `engineJs`.
98
+ */
99
+
100
+ /** The stages of the render phase, in the order a frame spends them. They sum to the frame's `render` phase. */
101
+ declare const RENDER_STAGES: readonly ["jsBefore", "engineJs", "wasmScene", "wasmPlan", "wasmCompute", "wasmEncode", "wasmPost", "wasmSubmit", "wasmPoll", "wasmTail", "wasmRendererGap", "wasmDatabaseGap", "wasmTargets", "wasmOther", "jsAfter"];
102
+ type RenderStage = (typeof RENDER_STAGES)[number];
103
+ /**
104
+ * Parts of a stage, published beside it and never added to the sum: `wasmPlan` holds all three, in the order the
105
+ * renderer runs them, and what is left of it is the rest of the prepare half.
106
+ */
107
+ declare const STAGE_PARTS: readonly ["planVirtualPages", "planDraws", "planShadowLists"];
108
+ type StagePart = (typeof STAGE_PARTS)[number];
109
+ /** One frame's stages in milliseconds, reused across frames so the read allocates nothing. */
110
+ type IFrameStageSample = Record<RenderStage | StagePart, number | undefined>;
111
+
66
112
  /**
67
113
  * Per-pass draw and triangle attribution, on by default, for every platform.
68
114
  *
@@ -118,6 +164,22 @@ interface IRenderPassSample {
118
164
  readonly kind: FramePassKind;
119
165
  readonly triangles: number;
120
166
  }
167
+ /**
168
+ * One resolved frame's GPU milliseconds by stage: `stages` sums the nested passes that carry the same
169
+ * scene name (three names its post passes `SSGI` and `AO`), and `total` is the whole frame.
170
+ */
171
+ interface IStageGpuReading {
172
+ readonly frame: number;
173
+ readonly stages: Readonly<Record<string, number>>;
174
+ readonly total: number;
175
+ }
176
+ /**
177
+ * The newest whole frame's GPU milliseconds by named stage on this renderer, or `undefined` before
178
+ * one resolved (or with neither a recorder installed nor an owned engine, or an adapter that grants
179
+ * no timestamp query). The `frame` number lets a reader count each resolved frame once. A stage that
180
+ * did not draw is absent.
181
+ */
182
+ declare function stageGpuReading(renderer: unknown): IStageGpuReading | undefined;
121
183
 
122
184
  type PlatformRuntime = "web" | "native";
123
185
  type PlatformOS = "android" | "ios" | "linux" | "macos" | "windows" | "unknown";
@@ -339,19 +401,29 @@ interface IFrameBudgetPassSummary {
339
401
  * it were a player's — `threenative-playtest perf` refuses to (`TN_PERF_VIRTUAL_DISPLAY`).
340
402
  */
341
403
  interface IFrameBudgetWindow {
342
- /** Browser Long Tasks, independent of vsync/GPU waits. Unavailable on hosts without this API. */
404
+ /**
405
+ * Browser Long Tasks, independent of vsync/GPU waits. Unavailable on hosts without this API.
406
+ * `count` and `longestMs` describe this window; `afterFirstFrameMs` is the run's startup figure.
407
+ */
343
408
  readonly longTasks: {
344
409
  readonly available: false;
345
410
  } | {
346
411
  readonly available: true;
412
+ /** Long Tasks observed inside this window, not since the page started. */
347
413
  readonly count: number;
414
+ /** This window's longest Long Task; 0 when it saw none. */
348
415
  readonly longestMs: number;
416
+ /** The run's longest task after the first frame: a startup number, not this window's. */
349
417
  readonly afterFirstFrameMs: number;
350
418
  };
351
419
  /** 1 for the first reported window, incrementing thereafter. */
352
420
  readonly window: number;
421
+ /** The web engine's job pool: `on (N)` workers, or `off (<reason>)`; absent off the Wasm engine. */
422
+ readonly threads?: string;
353
423
  /** Loop frames counted in this window, hitches excluded — one per present on the web. */
354
424
  readonly frames: number;
425
+ /** Debug-only elapsed time between completed report boundaries; absent on the first window. */
426
+ readonly durationMs?: number;
355
427
  /** Fixed simulation ticks in this window multiplied by the loop's step, when supplied. */
356
428
  readonly simulatedSeconds?: number;
357
429
  /** Frames excluded from the window because their present gap exceeded `hitchMs`. */
@@ -378,6 +450,16 @@ interface IFrameBudgetWindow {
378
450
  readonly presentedFps?: number;
379
451
  /** Interval between loop frames — the honest frame period where the loop presents every frame. */
380
452
  readonly presented: IFrameBudgetSummary;
453
+ /**
454
+ * Interval between frames the renderer drew. A declined frame (`renderSkips`) adds its time to the
455
+ * next drawn frame's interval, because the display showed the previous image for both. Reported
456
+ * beside `presented`, which gates keep reading; on the web this is what the player saw.
457
+ */
458
+ readonly drawn: IFrameBudgetSummary;
459
+ /** Loop frames the renderer drew: `frames - renderSkips`. */
460
+ readonly drawnFrames: number;
461
+ /** Derived from the mean `drawn` interval: drawn frames per second. */
462
+ readonly drawnFps: number;
381
463
  /** Duration of the frame callback itself, entry to exit. */
382
464
  readonly frame: IFrameBudgetSummary;
383
465
  /** Fixed simulation steps executed in the callback. */
@@ -480,6 +562,8 @@ interface IFrameBudgetWindow {
480
562
  * `gpuMain + gpuShadow + gpuOther` reconciles with `gpuMs` only when all three are present.
481
563
  */
482
564
  readonly gpuMain?: number;
565
+ /** Fresh frames in the same main-bucket ring as gpuMain; absent when unmeasured. */
566
+ readonly gpuMainSamples?: number;
483
567
  readonly gpuShadow?: number;
484
568
  readonly gpuOther?: number;
485
569
  readonly gpuCompute?: number;
@@ -518,8 +602,31 @@ interface IFrameBudgetWindow {
518
602
  readonly hostCalls?: IFrameBudgetSummary;
519
603
  readonly gpuBytes?: IFrameBudgetSummary;
520
604
  readonly jsAllocBytes?: IFrameBudgetSummary;
605
+ /** JS->Wasm crossings per frame, when the back end counts them (`createCrossingReader`). */
606
+ readonly bridgeCrossings?: IFrameBudgetSummary;
607
+ readonly dirtyTransforms?: IFrameBudgetSummary;
608
+ readonly castersMoving?: IFrameBudgetSummary;
609
+ /** Engine work counts per frame by name, when a playtest asked for them (`createEngineCounterReader`). */
610
+ readonly engine?: Readonly<Record<string, IFrameBudgetSummary>>;
521
611
  readonly simulationTick?: number;
522
612
  };
613
+ /**
614
+ * Where the callback's frame went (PRD-771), per stage in ms, one series per name. The render phase's
615
+ * stages (`RENDER_STAGES`) plus the `update`, `overlay`, `ui` and `residual` phases partition `frame`;
616
+ * `stageSum` is each frame's sum of those, so a window whose `stageSum` trails `frame` says how much
617
+ * time no stage named. `STAGE_PARTS` are pieces of `wasmPlan`, published beside it and not in the sum.
618
+ * Absent until a frame reported stages, and a name nothing measured is absent, never zero.
619
+ */
620
+ readonly stages?: Readonly<Record<string, IFrameBudgetSummary>>;
621
+ readonly stageSum?: IFrameBudgetSummary;
622
+ /**
623
+ * The mean of each stage over the window's slowest frames, the ones whose `stageSum` reaches its own p95: where
624
+ * the p95 frame goes, to read beside the stage's p50. `frames` is how many that was.
625
+ */
626
+ readonly stagesAtP95?: {
627
+ readonly frames: number;
628
+ readonly stages: Readonly<Record<string, number>>;
629
+ };
523
630
  }
524
631
  interface IFrameBudgetSimulation {
525
632
  readonly tick: () => number;
@@ -666,6 +773,11 @@ declare class FrameBudget {
666
773
  * An unknown kind throws rather than being dropped, the same fail-closed rule as a phase.
667
774
  */
668
775
  addRenderPasses(passes: readonly IRenderPassSample[]): void;
776
+ /**
777
+ * Records the frame's render-phase stages, from `createStageReader`. At most one call per frame; the
778
+ * object is read at `endFrame`, so a caller may reuse one sample across frames.
779
+ */
780
+ addStages(stages: IFrameStageSample): void;
669
781
  /**
670
782
  * Closes the frame and returns its phase split, or `undefined` when the frame was a hitch and
671
783
  * therefore excluded — a 27-second startup stall is not a frame time and must not enter a
@@ -977,6 +1089,9 @@ interface IGpuFrameObservation {
977
1089
  dispose(): void;
978
1090
  }
979
1091
 
1092
+ /** `filmic` is a fresh Unreal 5.8.3 project's curve and the default; the rest are the named overrides. */
1093
+ type RendererToneMapping = "filmic" | "aces" | "agx" | "neutral" | "none";
1094
+
980
1095
  /** The marker shared by alpha-antialiasing logs, playtests, and native diagnostics. */
981
1096
  declare const ALPHA_ANTIALIASING_MARKER = "TN_ALPHA_ANTIALIASING";
982
1097
  interface IAlphaAntialiasingReport {
@@ -1134,26 +1249,38 @@ interface IRenderChainRenderer {
1134
1249
  /** Install a graph and identify the authored world pass that follows the rendered scene root. */
1135
1250
  setOutputNode: RenderOutputSetter;
1136
1251
  }
1137
- /** Quality values are algorithm parameters, not appearance values. Templates own the latter. */
1252
+ /**
1253
+ * Quality values are algorithm parameters, not appearance values. Templates own the latter.
1254
+ *
1255
+ * `ssrMaxSteps` caps the mirror reflection march as Unreal caps it per tier (UE 5.8.3:
1256
+ * Engine/Shaders/Private/SSRT/SSRTReflections.usf:198-216, Engine/Config/BaseScalability.ini
1257
+ * `[ReflectionQuality@N]`). `high` is Epic, `r.SSR.Quality` 3: 8 steps on each of 4 rays, so the
1258
+ * one mirror ray gets the 32 steps. `medium` is Medium, quality 2: 16 steps on 1 ray. `low` takes
1259
+ * quality 1, 8 steps on 1 ray.
1260
+ */
1138
1261
  declare const RENDER_CHAIN_TIERS: {
1139
1262
  readonly high: {
1140
1263
  readonly denoiseIterations: 3;
1141
1264
  readonly sliceCount: 3;
1265
+ readonly ssrMaxSteps: 32;
1142
1266
  readonly stepCount: 16;
1143
1267
  };
1144
1268
  readonly low: {
1145
1269
  readonly denoiseIterations: 1;
1146
1270
  readonly sliceCount: 1;
1271
+ readonly ssrMaxSteps: 8;
1147
1272
  readonly stepCount: 12;
1148
1273
  };
1149
1274
  readonly medium: {
1150
1275
  readonly denoiseIterations: 2;
1151
1276
  readonly sliceCount: 2;
1277
+ readonly ssrMaxSteps: 16;
1152
1278
  readonly stepCount: 8;
1153
1279
  };
1154
1280
  readonly off: {
1155
1281
  readonly denoiseIterations: 0;
1156
1282
  readonly sliceCount: 0;
1283
+ readonly ssrMaxSteps: 0;
1157
1284
  readonly stepCount: 0;
1158
1285
  };
1159
1286
  };
@@ -1240,6 +1367,13 @@ interface IRenderChainVelocityReport {
1240
1367
  readonly measurementFrame?: number;
1241
1368
  }
1242
1369
  interface IRenderChainApplied {
1370
+ /** Actual GPU allocation sizes, absent until the owned temporal pass has rendered. */
1371
+ readonly stageSizes?: {
1372
+ readonly traa: {
1373
+ readonly input: readonly [number, number];
1374
+ readonly output: readonly [number, number];
1375
+ };
1376
+ };
1243
1377
  readonly contributions: readonly {
1244
1378
  readonly graphOutputChanged: boolean;
1245
1379
  readonly name: RenderChainStageId;
@@ -1313,6 +1447,19 @@ declare class RenderChain {
1313
1447
  dispose(): void;
1314
1448
  }
1315
1449
 
1450
+ /**
1451
+ * The renderer's own first-frame answer, with the inputs it is still short of so a launch that reached its
1452
+ * deadline can name what never arrived instead of reporting a bare timeout.
1453
+ */
1454
+ interface IStartupImageState {
1455
+ /** The renderer's answer: a world frame a player may see exists. */
1456
+ readonly ready: boolean;
1457
+ /** The exposure meter measured within tolerance of the target it owns. */
1458
+ readonly exposureSettled: boolean;
1459
+ /** Every active virtual shadow mapped its clip levels, and an ordinary world frame drew. */
1460
+ readonly shadowInputsReady: boolean;
1461
+ }
1462
+
1316
1463
  /** The standard buffer fields this renderer seam verifies; the device handle stays opaque. */
1317
1464
  interface IRendererStorageBuffer {
1318
1465
  readonly size: number;
@@ -1390,8 +1537,24 @@ interface IRendererLike {
1390
1537
  warmUpSettled?(): void;
1391
1538
  /** Marks a repeatable streamed warm-up boundary for the next first draw. */
1392
1539
  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;
1540
+ /**
1541
+ * Holds the native canvas at its last picture while the startup's first world frame is still cold: every frame
1542
+ * still draws, but takes no surface texture, so a world whose shadow and exposure inputs are not ready never
1543
+ * reaches the display. Present only on the Wasm engine; a renderer without it draws and presents as before.
1544
+ */
1545
+ setPresentationHeld?(held: boolean): void;
1546
+ /**
1547
+ * A held startup's first world frame: `ready` once an ordinary submission drew since the hold engaged, that
1548
+ * frame's shadow inputs are initialized, and this install's auto exposure measured within 3% of its target; the
1549
+ * two inputs say which one is still cold, so a launch that revealed at its deadline names what never arrived.
1550
+ * Absent wherever the hold is.
1551
+ */
1552
+ firstWorldFrame?(): IStartupImageState;
1553
+ /**
1554
+ * Performs one covered output-pipeline render without marking first present. `afterDraw` runs in
1555
+ * the same task as every draw it makes, the frame gate's retries included, to repaint a cover.
1556
+ */
1557
+ warmUpWorldPass?(scene: Object3D, camera: Camera, targetScene?: Object3D, afterDraw?: () => void): void | Promise<void>;
1395
1558
  /**
1396
1559
  * What alpha antialiasing did with the multisampled surface, and why, when it did nothing.
1397
1560
  *
@@ -1594,6 +1757,9 @@ interface IRendererLike {
1594
1757
  * caller; a pinned game never reaches this, which is what makes "pinned" mean pinned.
1595
1758
  */
1596
1759
  setResolutionScale(scale: number, scaleSource: "auto" | "auto-pinned"): void;
1760
+ /** True only while the owned temporal resolve reconstructs display pixels. */
1761
+ temporalUpscale?(): boolean;
1762
+ temporalUpscaleStartScale?(): number | undefined;
1597
1763
  /**
1598
1764
  * What this renderer is actually drawing at. Read once per frame-budget window so every fps
1599
1765
  * number is self-describing; a record and a tree once disagreed about the scale for a whole
@@ -1623,6 +1789,13 @@ interface IRendererOptions {
1623
1789
  alphaAntialiasing?: boolean;
1624
1790
  /** Requests multisample antialiasing from the renderer. Defaults to true. */
1625
1791
  antialias?: boolean;
1792
+ /**
1793
+ * The tone curve a WebGPU renderer starts with. Defaults to `filmic`, a fresh Unreal 5.8.3
1794
+ * project's curve; `aces`, `agx`, `neutral` and `none` (three's linear output) are the named
1795
+ * overrides. A renderer that cannot run the curve keeps ACES and reports `TN_TONEMAP`. Setting
1796
+ * `renderer.raw.toneMapping` afterwards still wins.
1797
+ */
1798
+ toneMapping?: RendererToneMapping;
1626
1799
  canvas?: HTMLCanvasElement;
1627
1800
  gpuTimestampFrameInterval?: number;
1628
1801
  preferWebGPU?: boolean;
@@ -1656,4 +1829,4 @@ interface IRendererOptions {
1656
1829
  }>) => unknown;
1657
1830
  }
1658
1831
 
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 };
1832
+ export { RENDER_CHAIN_STAGE_ORDER as $, type IRenderChainBudgetWindow as A, type IRenderChainDroppedStage as B, type IRenderChainOptions as C, DEFAULT_PIPELINE_CENSUS_LIMIT as D, type IRenderChainRenderer as E, type FramePassKind as F, type IRenderChainRequest as G, type IRenderChainStage as H, type IRendererLike as I, type IRenderChainStageContext as J, type IRenderChainVelocityMeasurement as K, type IRenderChainVelocityReport as L, type IRenderChainVelocityRequest as M, type IRenderChainVelocityResult as N, type ITargetFps as O, type IVelocityRenderPass as P, MAX_TARGET_FPS as Q, type MainDrawSource as R, PIPELINE_CENSUS_CAPABILITY as S, PIPELINE_CENSUS_VERSION as T, PipelineCensus as U, type PipelineCensusMode as V, type PipelineCensusStatus as W, type PlatformFormFactor as X, type PlatformOS as Y, type PlatformRuntime as Z, RENDER_CHAIN_MARKER as _, type IFrameBudgetWindow as a, RENDER_CHAIN_TIERS as a0, RenderChain as a1, type RenderChainSource as a2, type RenderChainStageId as a3, type RenderChainStageName as a4, type RenderChainTier as a5, type RenderChainTierRequest as a6, type RenderChainVelocitySource as a7, type RendererToneMapping as a8, type TargetFpsSource as a9, VELOCITY_OUTPUT_NAME as aa, VELOCITY_PREVIOUS_BONE_MATRICES as ab, VELOCITY_PREVIOUS_INSTANCE_MATRICES as ac, VELOCITY_PREVIOUS_WORLD_MATRIX as ad, VelocityTracker as ae, counterDeviceOf as af, createPipelineCensus as ag, ensureVelocityOutput as ah, getPlatform as ai, isMobile as aj, isNative as ak, isTouchscreenAvailable as al, isWeb as am, prewarm as an, readRenderChainObservation as ao, readRenderChainReport as ap, readVelocityPreviousBoneMatrices as aq, readVelocityPreviousMatrices as ar, readVelocityPreviousWorldMatrix as as, resolveTargetFps as at, snapRefreshRate as au, stageGpuReading as av, velocityTexture as aw, withVelocityContext as ax, type IFrameBudgetSimulation as b, type IRenderPassSample as c, type IFramePhaseSample as d, type IPipelineCensus as e, type IRendererOptions as f, type IFrameBudgetOptions as g, type IStageGpuReading as h, DEFAULT_TARGET_FPS as i, FRAME_BUDGET_MARKER as j, FRAME_BUDGET_PHASES as k, FRAME_HITCH_MARKER as l, FrameBudget as m, type FrameBudgetPhase as n, FrameCounters as o, type ICounterDevice as p, type IFrameBudgetPassSummary as q, type IFrameBudgetSummary as r, type IFrameCounters as s, type IPipelineCensusCounts as t, type IPipelineCensusEvent as u, type IPipelineCensusOptions as v, type IPipelineProvenance as w, type IPipelineShaderObservation as x, type IPlatformInfo as y, type IRenderChainApplied as z };
@@ -66,6 +66,13 @@ declare const UI_INTENT_MESSAGE = "tn:intent";
66
66
  * from it lies in exactly the sessions where somebody is trying to measure.
67
67
  */
68
68
  declare const UI_DEV_METRICS_MESSAGE = "tn:dev-metrics";
69
+ /**
70
+ * The startup phase the game end publishes: `covered` while the loading cover is up, `ready` from
71
+ * the frame the cover lifts. The UI realm cannot read `ctx.startup`, so this is how `useUiState`
72
+ * knows to return `undefined` until the player can see the page. A game that never sends it (an
73
+ * older core) reads as uncovered.
74
+ */
75
+ declare const UI_STARTUP_MESSAGE = "tn:startup";
69
76
  /**
70
77
  * The intent the UI layer sends once, when its tree has rendered and its rectangles are published.
71
78
  *
@@ -151,7 +158,9 @@ interface IUiStatePublisher {
151
158
  interface IUiStateMirror<T> {
152
159
  /** The last state the game published, or undefined before the first frame arrives. */
153
160
  get(): T | undefined;
154
- /** Called after each accepted publication. Returns an unsubscribe function. */
161
+ /** True while the game reports its loading cover up; false before it says so and after it lifts. */
162
+ covered(): boolean;
163
+ /** Called after each accepted publication, and when the cover state changes. Returns an unsubscribe function. */
155
164
  subscribe(listener: () => void): () => void;
156
165
  /** Stop listening. */
157
166
  stop(): void;
@@ -311,4 +320,4 @@ interface IScopeLike extends IEventTargetLike {
311
320
  */
312
321
  declare function publishHitRegions(options: IRegistryOptions): IHitRegionRegistry;
313
322
 
314
- export { GAME_STATE_MESSAGE, HIT_REGIONS_MESSAGE, type IHitRegion, type IHitRegionRegistry, INTERACTIVE_ATTRIBUTE, type IPublishableStore, type IUiBridge, type IUiMessage, type IUiStateMirror, type IUiStatePublisher, UI_BRIDGE_GLOBALS, UI_DEV_METRICS_MESSAGE, UI_INTENT_MESSAGE, UI_READY_INTENT, type UiBridgeEnd, type UiBridgeTransport, connectUiBridge, onUiIntent, publishHitRegions, publishUiState, sendUiIntent, subscribeUiState };
323
+ export { GAME_STATE_MESSAGE, HIT_REGIONS_MESSAGE, type IHitRegion, type IHitRegionRegistry, INTERACTIVE_ATTRIBUTE, type IPublishableStore, type IUiBridge, type IUiMessage, type IUiStateMirror, type IUiStatePublisher, UI_BRIDGE_GLOBALS, UI_DEV_METRICS_MESSAGE, UI_INTENT_MESSAGE, UI_READY_INTENT, UI_STARTUP_MESSAGE, type UiBridgeEnd, type UiBridgeTransport, connectUiBridge, onUiIntent, publishHitRegions, publishUiState, sendUiIntent, subscribeUiState };
package/dist/ui-layer.js CHANGED
@@ -3,6 +3,7 @@ var HIT_REGIONS_MESSAGE = "tn:hit-regions";
3
3
  var GAME_STATE_MESSAGE = "tn:state";
4
4
  var UI_INTENT_MESSAGE = "tn:intent";
5
5
  var UI_DEV_METRICS_MESSAGE = "tn:dev-metrics";
6
+ var UI_STARTUP_MESSAGE = "tn:startup";
6
7
  var UI_READY_INTENT = "tn:ready";
7
8
  var UI_BRIDGE_GLOBALS = {
8
9
  /** UI end, inbound: the host calls this with one JSON string. */
@@ -129,12 +130,35 @@ function installInbound(scope, key, deliver) {
129
130
  if (installed.receivers.size === 0 && scope[key] === installed.dispatch) scope[key] = void 0;
130
131
  };
131
132
  }
133
+ var LOOPBACK_KEY = "__tnUiLoopback";
134
+ function installLoopback(scope) {
135
+ const search = scope.location?.search;
136
+ if (typeof search !== "string" || new URLSearchParams(search).get("tnUiLoopback") !== "1") return;
137
+ if (scope[LOOPBACK_KEY] !== void 0) return;
138
+ const { port1: gamePort, port2: uiPort } = new MessageChannel();
139
+ const receive = (key) => (event) => scope[key]?.(event.data);
140
+ gamePort.onmessage = receive(UI_BRIDGE_GLOBALS.gameReceive);
141
+ uiPort.onmessage = receive(UI_BRIDGE_GLOBALS.uiReceive);
142
+ scope[UI_BRIDGE_GLOBALS.gamePost] = (frame) => gamePort.postMessage(frame);
143
+ scope[UI_BRIDGE_GLOBALS.uiHost] = { postMessage: (frame) => uiPort.postMessage(frame) };
144
+ scope.__tnUiOverlayAttached = () => true;
145
+ scope[LOOPBACK_KEY] = {
146
+ close() {
147
+ gamePort.close();
148
+ uiPort.close();
149
+ for (const key of [UI_BRIDGE_GLOBALS.gamePost, UI_BRIDGE_GLOBALS.uiHost, LOOPBACK_KEY])
150
+ scope[key] = void 0;
151
+ scope.__tnUiOverlayAttached = void 0;
152
+ }
153
+ };
154
+ }
132
155
  function connectUiBridge(options) {
133
156
  const { end } = options;
134
157
  if (end !== "game" && end !== "ui") {
135
158
  throw new Error(`TN_UI_BRIDGE_END_INVALID: expected 'game' or 'ui', got '${String(end)}'.`);
136
159
  }
137
160
  const scope = options.scope ?? globalThis;
161
+ installLoopback(scope);
138
162
  const listeners = /* @__PURE__ */ new Set();
139
163
  const deliver = (frame) => {
140
164
  const message = parseFrame(frame);
@@ -204,6 +228,31 @@ function connectUiBridge(options) {
204
228
  };
205
229
  }
206
230
 
231
+ // src/profiling/debug-telemetry.ts
232
+ var DEBUG_GLOBAL = "__THREENATIVE_DEBUG__";
233
+ function debugRequested() {
234
+ const host = globalThis;
235
+ return host.process?.env?.TN_DEBUG === "1" || globalThis[DEBUG_GLOBAL] === true || /[?&]tnDebug=1(?:&|$)/u.test(globalThis.location?.search ?? "");
236
+ }
237
+ function countDebug(name, value, area, caller, unit = "count") {
238
+ if (!Number.isFinite(value) || value < 0)
239
+ throw new Error(`TN_DEBUG: invalid ${name} observation.`);
240
+ const host = globalThis;
241
+ host.__tnEngineCost ??= {};
242
+ host.__tnDebugSources ??= {};
243
+ host.__tnEngineCost[name] = (host.__tnEngineCost[name] ?? 0) + value;
244
+ host.__tnDebugSources[name] ??= { area, caller, unit };
245
+ }
246
+ function measureDebug(name, area, caller, run) {
247
+ const start = performance.now();
248
+ try {
249
+ return run();
250
+ } finally {
251
+ countDebug(`${name}Ms`, performance.now() - start, area, caller, "ms");
252
+ countDebug(`${name}Calls`, 1, area, caller);
253
+ }
254
+ }
255
+
207
256
  // src/ui-state.ts
208
257
  var microtask = (flush) => {
209
258
  void Promise.resolve().then(flush);
@@ -215,6 +264,11 @@ function publishUiState(bridge, store, options = {}) {
215
264
  );
216
265
  }
217
266
  const schedule = options.schedule ?? microtask;
267
+ const debug = debugRequested();
268
+ const serialize = debug ? (state) => {
269
+ countDebug("uiSerializations", 1, "ui", "publishUiState");
270
+ return measureDebug("uiSerialize", "ui", "publishUiState", () => serializeUiState(state));
271
+ } : serializeUiState;
218
272
  const read = () => store.getPublishedState === void 0 ? store.getState() : store.getPublishedState();
219
273
  let stopped = false;
220
274
  let queued = false;
@@ -222,18 +276,27 @@ function publishUiState(bridge, store, options = {}) {
222
276
  const send = (state, frame) => {
223
277
  lastFrame = frame;
224
278
  postUiState(bridge, state, frame);
279
+ if (debug) {
280
+ countDebug("uiMessages", 1, "ui", "publishUiState");
281
+ countDebug(
282
+ "uiMessageBytes",
283
+ new TextEncoder().encode(frame).byteLength,
284
+ "ui",
285
+ "publishUiState"
286
+ );
287
+ }
225
288
  };
226
289
  const publish = () => {
227
290
  if (stopped) return;
228
291
  const state = read();
229
- send(state, serializeUiState(state));
292
+ send(state, serialize(state));
230
293
  };
231
294
  const flush = () => {
232
295
  queued = false;
233
296
  if (stopped) return;
234
297
  if (!bridge.hasPeer()) return;
235
298
  const state = read();
236
- const frame = serializeUiState(state);
299
+ const frame = serialize(state);
237
300
  if (frame === lastFrame) return;
238
301
  send(state, frame);
239
302
  };
@@ -259,7 +322,15 @@ function subscribeUiState(bridge) {
259
322
  }
260
323
  const listeners = /* @__PURE__ */ new Set();
261
324
  let current;
325
+ let covered = false;
262
326
  const off = bridge.onMessage((message) => {
327
+ if (message.type === UI_STARTUP_MESSAGE) {
328
+ const next = message.phase !== "ready";
329
+ if (next === covered) return;
330
+ covered = next;
331
+ for (const listener of [...listeners]) listener();
332
+ return;
333
+ }
263
334
  if (message.type !== GAME_STATE_MESSAGE) return;
264
335
  const state = message.state;
265
336
  if (typeof state !== "object" || state === null || Array.isArray(state)) {
@@ -270,6 +341,7 @@ function subscribeUiState(bridge) {
270
341
  });
271
342
  return {
272
343
  get: () => current,
344
+ covered: () => covered,
273
345
  subscribe(listener) {
274
346
  listeners.add(listener);
275
347
  return () => listeners.delete(listener);
@@ -315,7 +387,7 @@ var INTERACTIVE_ATTRIBUTE = "data-tn-interactive";
315
387
  function quantize(value) {
316
388
  return Math.round(value * 1e5) / 1e5;
317
389
  }
318
- var TRANSITION_START = ["transitionrun", "transitionstart", "animationstart"];
390
+ var TRANSITION_START = ["transitionstart", "animationstart"];
319
391
  var TRANSITION_END = [
320
392
  "transitionend",
321
393
  "transitioncancel",
@@ -474,4 +546,4 @@ function isDevelopment() {
474
546
  return import.meta.env?.DEV === true;
475
547
  }
476
548
 
477
- export { GAME_STATE_MESSAGE, HIT_REGIONS_MESSAGE, INTERACTIVE_ATTRIBUTE, UI_BRIDGE_GLOBALS, UI_DEV_METRICS_MESSAGE, UI_INTENT_MESSAGE, UI_READY_INTENT, connectUiBridge, onUiIntent, publishHitRegions, publishUiState, sendUiIntent, subscribeUiState };
549
+ export { GAME_STATE_MESSAGE, HIT_REGIONS_MESSAGE, INTERACTIVE_ATTRIBUTE, UI_BRIDGE_GLOBALS, UI_DEV_METRICS_MESSAGE, UI_INTENT_MESSAGE, UI_READY_INTENT, UI_STARTUP_MESSAGE, connectUiBridge, onUiIntent, publishHitRegions, publishUiState, sendUiIntent, subscribeUiState };
@@ -0,0 +1,36 @@
1
+ /**
2
+ * The worker game host (PRD-752): the page keeps the DOM, the canvas and the input, while the
3
+ * unchanged portable game runs in a dedicated worker on an OffscreenCanvas.
4
+ *
5
+ * A worker cannot reach `window`, `document` or `ResizeObserver`, so the page forwards what the
6
+ * game would have read, one plain message at a time. The canvas frame and the UI bridge travel on
7
+ * their own ports: the game's start is slow, and a HUD that mounts first must not wait for it.
8
+ */
9
+ /** The realm `serveWorkerGame` runs in. Narrowed, because a test cannot build a real worker scope. */
10
+ type WorkerScope = EventTarget & Record<string, unknown> & {
11
+ postMessage(data: unknown): void;
12
+ };
13
+ /**
14
+ * Runs inside the worker: wire the page's messages to the unchanged portable game.
15
+ *
16
+ * Call it last in the worker entry, after the game module evaluated: it posts the ready message
17
+ * the page waits for before it sends the canvas.
18
+ * @situation run the game loop in a web worker so a busy page cannot stall its frames
19
+ * @example serveWorkerGame(game);
20
+ */
21
+ declare function serveWorkerGame(game: {
22
+ start(): Promise<void>;
23
+ }, scope?: WorkerScope): void;
24
+ /**
25
+ * Runs on the page: own the canvas and the DOM, and feed the worker game.
26
+ *
27
+ * Call it before the UI mounts: the HUD's bridge host globals exist from this call on.
28
+ * @situation host a worker-run game's canvas, input and HUD on the page
29
+ * @example const handle = startWorkerGame(new Worker(new URL("./worker.ts", import.meta.url), { type: "module" }), root);
30
+ */
31
+ declare function startWorkerGame(worker: Worker, container: HTMLElement): {
32
+ ready: Promise<void>;
33
+ stop(): void;
34
+ };
35
+
36
+ export { type WorkerScope, serveWorkerGame, startWorkerGame };