@threenative/core 0.3.6 → 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-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/snow-field.ts CHANGED
@@ -94,6 +94,8 @@ const RECOVERED_COMPACTION = 0.008;
94
94
  const WIND_EROSION = 0.00065;
95
95
  /** Deposition burial rate per metre of fill. */
96
96
  const DEPOSITION_BURIAL = 26;
97
+ /** Past this many separate windows a take is one box: a long drag must not grow the list. */
98
+ const MAX_UNTAKEN_WINDOWS = 32;
97
99
  /** Hard ceiling on cells one contact may span, so a malformed extent fails instead of allocating. */
98
100
  const MAX_CONTACT_CELLS = 1 << 20;
99
101
 
@@ -257,6 +259,7 @@ export class SnowField {
257
259
  #version = 0;
258
260
  #dirty: IHeightfieldRegionBounds | undefined;
259
261
  #untaken: IHeightfieldRegionBounds | undefined;
262
+ #untakenWindows: IHeightfieldRegionBounds[] = [];
260
263
  #scratch = new Float32Array(0);
261
264
 
262
265
  constructor(options: ISnowFieldOptions) {
@@ -325,9 +328,23 @@ export class SnowField {
325
328
  takeDirtyRegion(): IHeightfieldRegionBounds | undefined {
326
329
  const region = this.#untaken;
327
330
  this.#untaken = undefined;
331
+ this.#untakenWindows = [];
328
332
  return region;
329
333
  }
330
334
 
335
+ /**
336
+ * The windows written since the previous call, then forgotten. Windows that overlap or touch
337
+ * are one window, so two bodies a long way apart are two small windows, where
338
+ * `takeDirtyRegion` returns the large box around both. A renderer that uploads only what moved
339
+ * takes this. Like `takeDirtyRegion` it has one owner, and taking either one empties both.
340
+ */
341
+ takeDirtyRegions(): readonly IHeightfieldRegionBounds[] {
342
+ const windows = this.#untakenWindows;
343
+ this.#untaken = undefined;
344
+ this.#untakenWindows = [];
345
+ return windows;
346
+ }
347
+
331
348
  /** Bytes retained by the four snow channels and the base terrain copy. */
332
349
  get memoryBytes(): number {
333
350
  return (4 * this.#indent.length + this.#base.length) * Float32Array.BYTES_PER_ELEMENT;
@@ -739,6 +756,35 @@ export class SnowField {
739
756
  this.field.updateHeights({ ...bounds, heights });
740
757
  this.#dirty = { ...bounds };
741
758
  this.#untaken = unionBounds(this.#untaken, bounds);
759
+ this.#untakenWindows = addWindow(this.#untakenWindows, bounds);
742
760
  this.#version += 1;
743
761
  }
744
762
  }
763
+
764
+ /** Add `next` to `windows`, merging every window it overlaps or touches into one. */
765
+ function addWindow(
766
+ windows: readonly IHeightfieldRegionBounds[],
767
+ next: IHeightfieldRegionBounds,
768
+ ): IHeightfieldRegionBounds[] {
769
+ let merged = next;
770
+ let rest = [...windows];
771
+ for (let again = true; again; ) {
772
+ again = false;
773
+ const keep: IHeightfieldRegionBounds[] = [];
774
+ for (const window of rest) {
775
+ const apart =
776
+ window.column > merged.column + merged.columns ||
777
+ merged.column > window.column + window.columns ||
778
+ window.row > merged.row + merged.rows ||
779
+ merged.row > window.row + window.rows;
780
+ if (apart) keep.push(window);
781
+ else {
782
+ merged = unionBounds(merged, window);
783
+ again = true;
784
+ }
785
+ }
786
+ rest = keep;
787
+ }
788
+ const all = [...rest, merged];
789
+ return all.length > MAX_UNTAKEN_WINDOWS ? [all.reduce((a, b) => unionBounds(a, b))] : all;
790
+ }
package/src/softbody.ts CHANGED
@@ -196,10 +196,11 @@ function clothPass(options: {
196
196
  const nextPosition = position.add(velocity.mul(options.halfStep)).toVar();
197
197
  const collision = options.collision;
198
198
  if (collision !== undefined) {
199
- Loop({ type: "uint", start: 0, end: collision.capacity }, ({ i }) => {
200
- If(i.lessThan(collision.count), () => {
201
- const center = collision.bounds.element(i.mul(2)).xyz;
202
- const halfExtents = collision.bounds.element(i.mul(2).add(1)).xyz;
199
+ // Unrolled over the capacity: the owned engine reads a uniform array at a constant index only.
200
+ for (let box = 0; box < collision.capacity; box++) {
201
+ If(collision.count.greaterThan(box), () => {
202
+ const center = collision.bounds.element(box * 2).xyz;
203
+ const halfExtents = collision.bounds.element(box * 2 + 1).xyz;
203
204
  const currentRelative = position.sub(center);
204
205
  const relative = nextPosition.sub(center);
205
206
  const withinX = relative.x.abs().lessThanEqual(halfExtents.x);
@@ -286,7 +287,7 @@ function clothPass(options: {
286
287
  });
287
288
  });
288
289
  });
289
- });
290
+ }
290
291
  }
291
292
  If(metadata.x.greaterThan(0), () => {
292
293
  options.targetPositions
@@ -0,0 +1,168 @@
1
+ import { Box3, type Camera, Frustum, Matrix4, type Object3D } from "three";
2
+ import type { IResolvedAsset } from "./assets.js";
3
+ import { GEOMETRY_ASSET_KEY } from "./geometry-capture.js";
4
+
5
+ /** Why a file the reveal waited for shows nothing at the reveal. */
6
+ export type OffscreenReason = "hidden" | "not-placed" | "outside-view";
7
+
8
+ export interface IStartupOffscreenFile {
9
+ readonly bytes: number;
10
+ readonly path: string;
11
+ readonly reason: OffscreenReason;
12
+ }
13
+
14
+ /**
15
+ * What the reveal waited for, split by whether the spawn camera shows it.
16
+ *
17
+ * Measured, never configured: nothing here is compared with a fixed size. `warn` is a ratio of two
18
+ * numbers from the same run (off-screen bytes against visible bytes), so no constant needs
19
+ * revisiting when links or games change.
20
+ */
21
+ export interface IStartupOffscreenBytes {
22
+ /** Every sized byte the reveal waited for through `ctx.assets`. */
23
+ readonly awaitedBytes: number;
24
+ /** The fix, so a reader of one console line needs no other document. */
25
+ readonly fix: string;
26
+ /** Bytes of models with an object in view. */
27
+ readonly visibleBytes: number;
28
+ /** Bytes of models with no visible object in the frustum. */
29
+ readonly offscreenBytes: number;
30
+ /** Textures and audio: no scene object ties them to a view, so the engine does not guess. */
31
+ readonly unattributedBytes: number;
32
+ /** Awaited files whose size the manifest does not record, so they are in no byte count. */
33
+ readonly unsizedFiles: number;
34
+ /** The five largest off-screen files. */
35
+ readonly top: readonly IStartupOffscreenFile[];
36
+ /** Most of the wait bought nothing on screen: off-screen bytes exceed visible bytes. */
37
+ readonly warn: boolean;
38
+ }
39
+
40
+ export const STARTUP_OFFSCREEN_BYTES_MARKER = "TN_STARTUP_OFFSCREEN_BYTES";
41
+
42
+ export const STARTUP_OFFSCREEN_FIX =
43
+ "Stream these files with WorldCells, or ctx.assets.prefetch them after the reveal, and keep " +
44
+ "awaiting everything the spawn camera sees. A not-placed file may also be geometry the game " +
45
+ "merged into a new buffer, which drops its provenance: check that before moving it.";
46
+
47
+ const TOP_FILES = 5;
48
+
49
+ function stampOf(userData: unknown): string | undefined {
50
+ const stamped = (userData as Record<string, unknown> | undefined)?.[GEOMETRY_ASSET_KEY];
51
+ return typeof stamped === "string" && stamped !== "" ? stamped : undefined;
52
+ }
53
+
54
+ /**
55
+ * Which logical paths have an object in the scene, and whether any of them shows.
56
+ *
57
+ * A path is stamped on the model root and on every mesh geometry the loader returned, so an
58
+ * instanced batch built from a model's geometry keeps it even though the root never enters the
59
+ * scene. "Shows" means visible through the whole ancestry with world bounds in the frustum.
60
+ */
61
+ function holders(root: Object3D, camera: Camera): Map<string, { shown: boolean; placed: boolean }> {
62
+ camera.updateWorldMatrix(true, false);
63
+ const frustum = new Frustum().setFromProjectionMatrix(
64
+ new Matrix4().multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse),
65
+ );
66
+ const found = new Map<string, { shown: boolean; placed: boolean }>();
67
+ const box = new Box3();
68
+ const visit = (object: Object3D, hidden: boolean): void => {
69
+ const isHidden = hidden || !object.visible;
70
+ const geometry = (object as Object3D & { geometry?: { userData?: unknown } }).geometry;
71
+ for (const path of new Set([stampOf(object.userData), stampOf(geometry?.userData)])) {
72
+ if (path === undefined) continue;
73
+ const entry = found.get(path) ?? { placed: false, shown: false };
74
+ found.set(path, entry);
75
+ if (isHidden) continue;
76
+ entry.placed = true;
77
+ if (!entry.shown && !box.setFromObject(object).isEmpty() && frustum.intersectsBox(box))
78
+ entry.shown = true;
79
+ }
80
+ for (const child of object.children) visit(child, isHidden);
81
+ };
82
+ visit(root, false);
83
+ return found;
84
+ }
85
+
86
+ /**
87
+ * A one-off measurement walk, like the playtest observer's, under the same mark: three-native's
88
+ * bridge census then never bills its re-reads of every child to the game's frame.
89
+ */
90
+ export function unbilled<T>(work: () => T): T {
91
+ const host = globalThis as { __tnPlaytestObserving?: number };
92
+ host.__tnPlaytestObserving = (host.__tnPlaytestObserving ?? 0) + 1;
93
+ try {
94
+ return work();
95
+ } finally {
96
+ host.__tnPlaytestObserving -= 1;
97
+ }
98
+ }
99
+
100
+ /**
101
+ * Split the bytes a reveal waited for into what the spawn camera shows and what it does not.
102
+ *
103
+ * `resolved` is `ctx.assets.resolved` at the reveal: every path that settled by then, with the
104
+ * kind and manifest size the loader recorded. A path with no stamp anywhere in `root` reads
105
+ * `not-placed`; a path stamped only under a hidden node reads `hidden`; otherwise a path whose
106
+ * bounds miss the frustum reads `outside-view`.
107
+ */
108
+ export function measureStartupOffscreenBytes(
109
+ resolved: ReadonlyMap<string, IResolvedAsset>,
110
+ root: Object3D,
111
+ camera: Camera,
112
+ ): IStartupOffscreenBytes {
113
+ const objects = unbilled(() => holders(root, camera));
114
+ let awaitedBytes = 0;
115
+ let visibleBytes = 0;
116
+ let unattributedBytes = 0;
117
+ let unsizedFiles = 0;
118
+ const offscreen: IStartupOffscreenFile[] = [];
119
+ // A load downloads its own file plus the shared images and lightmaps it names, and two models
120
+ // can share an image. Each url counts once: models in view first, so a file any visible model
121
+ // needs is visible, then textures and audio, then the models the camera does not show.
122
+ const counted = new Set<string>();
123
+ const take = (asset: IResolvedAsset): number => {
124
+ let bytes = 0;
125
+ for (const file of asset.files ?? [{ bytes: asset.bytes ?? 0, url: asset.url }]) {
126
+ if (counted.has(file.url)) continue;
127
+ counted.add(file.url);
128
+ bytes += file.bytes;
129
+ }
130
+ awaitedBytes += bytes;
131
+ return bytes;
132
+ };
133
+ const sized = [...resolved].filter(([, asset]) => {
134
+ if ((asset.bytes ?? 0) > 0) return true;
135
+ unsizedFiles += 1;
136
+ return false;
137
+ });
138
+ const rank = ([path, asset]: [string, IResolvedAsset]): number =>
139
+ asset.kind !== "model" ? 1 : objects.get(path)?.shown === true ? 0 : 2;
140
+ sized.sort((a, b) => rank(a) - rank(b));
141
+ for (const [path, asset] of sized) {
142
+ const bytes = take(asset);
143
+ if (asset.kind !== "model") {
144
+ unattributedBytes += bytes;
145
+ continue;
146
+ }
147
+ const holder = objects.get(path);
148
+ if (holder?.shown === true) visibleBytes += bytes;
149
+ else if (bytes > 0)
150
+ offscreen.push({
151
+ bytes,
152
+ path,
153
+ reason: holder === undefined ? "not-placed" : holder.placed ? "outside-view" : "hidden",
154
+ });
155
+ }
156
+ offscreen.sort((a, b) => b.bytes - a.bytes);
157
+ const offscreenBytes = offscreen.reduce((sum, file) => sum + file.bytes, 0);
158
+ return {
159
+ awaitedBytes,
160
+ fix: STARTUP_OFFSCREEN_FIX,
161
+ offscreenBytes,
162
+ top: offscreen.slice(0, TOP_FILES),
163
+ unattributedBytes,
164
+ unsizedFiles,
165
+ visibleBytes,
166
+ warn: offscreenBytes > visibleBytes,
167
+ };
168
+ }
@@ -1,5 +1,31 @@
1
1
  export type StartupCompile = () => Promise<void> | void;
2
2
 
3
+ /**
4
+ * The renderer's own first-frame answer, with the inputs it is still short of so a launch that reached its
5
+ * deadline can name what never arrived instead of reporting a bare timeout.
6
+ */
7
+ export interface IStartupImageState {
8
+ /** The renderer's answer: a world frame a player may see exists. */
9
+ readonly ready: boolean;
10
+ /** The exposure meter measured within tolerance of the target it owns. */
11
+ readonly exposureSettled: boolean;
12
+ /** Every active virtual shadow mapped its clip levels, and an ordinary world frame drew. */
13
+ readonly shadowInputsReady: boolean;
14
+ }
15
+
16
+ /** The answer of a renderer with nothing to wait for, and of a predicate that threw. */
17
+ const IMAGE_READY: IStartupImageState = {
18
+ exposureSettled: true,
19
+ ready: true,
20
+ shadowInputsReady: true,
21
+ };
22
+ /** A predicate that answers a plain `false` names no input: both are reported cold, which is its own answer. */
23
+ const IMAGE_COLD: IStartupImageState = {
24
+ exposureSettled: false,
25
+ ready: false,
26
+ shadowInputsReady: false,
27
+ };
28
+
3
29
  export interface IStartupReadinessOptions {
4
30
  /** Maximum wall-clock time spent waiting for first-use compilation. */
5
31
  readonly compileBudgetMs?: number;
@@ -19,6 +45,20 @@ export interface IStartupReadinessOptions {
19
45
  readonly stableWindowMs?: number;
20
46
  /** Default ceiling on a single `hold()`, when the caller does not give one. */
21
47
  readonly holdBudgetMs?: number;
48
+ /**
49
+ * Whether the renderer's own first real world frame exists. Read on every rendered frame, and required
50
+ * before readiness resolves, after the compile and stable-window budgets as well: those two timers answer
51
+ * what the *framework* cost, never that the picture behind the cover is the world. Absent means the caller
52
+ * has nothing to wait for (every renderer without the native presentation seam). A throwing predicate
53
+ * fails open, as a throwing hold does, so a broken read costs a frame the player did not see rather than a
54
+ * launch that never finishes.
55
+ *
56
+ * A predicate that says which input is still cold answers `IStartupImageState` instead of `false`; the
57
+ * deadline below prints that answer. One that never turns true — a black or unlit opening whose meter never
58
+ * measures, a sun that moves every frame and resets every shadow level, a target that keeps moving — costs
59
+ * `STARTUP_IMAGE_TIMEOUT_MS` of cover and then reveals, rather than costing the game its launch.
60
+ */
61
+ readonly imageReady?: () => boolean | IStartupImageState;
22
62
  /**
23
63
  * Run after every hold settles and before readiness resolves.
24
64
  *
@@ -71,6 +111,17 @@ export const STARTUP_STABLE_WINDOW_MS = 10_000;
71
111
  * poorer-looking game and never a game that does not start.
72
112
  */
73
113
  export const STARTUP_HOLD_BUDGET_MS = 45_000;
114
+ /**
115
+ * How long the renderer's own first-frame wait may outlast the frame window before the cover lifts anyway.
116
+ *
117
+ * It is the one wait a game cannot bound for itself, and real openings leave it outstanding for good: a menu or
118
+ * a space scene that is genuinely black, where the exposure meter never measures; a sun direction that changes
119
+ * every frame, where `atlas.cpp` resets every level and grants one per frame, so the atlas never reports ready;
120
+ * a meter target that keeps moving. Three seconds covers a healthy startup's cold frames many times over — the
121
+ * shadow pages map in the first few held frames and the meter settles soon after — and is short enough that such
122
+ * an opening is a launch that worked instead of a launch that hung.
123
+ */
124
+ export const STARTUP_IMAGE_TIMEOUT_MS = 3_000;
74
125
 
75
126
  /** One registered hold: the game's own launch work, and the bounded wait for it. */
76
127
  interface IHold {
@@ -98,6 +149,10 @@ export class StartupReadiness {
98
149
  readonly #holds = new Map<string, IHold>();
99
150
  #holdBudgetMs: number;
100
151
  #afterHolds: (() => Promise<void> | void) | undefined;
152
+ #imageReady: (() => boolean | IStartupImageState) | undefined;
153
+ #imageTimer: ReturnType<typeof setTimeout> | undefined;
154
+ #imageWaitedFrom = 0;
155
+ #imageTimedOut = false;
101
156
  #compileTimer: ReturnType<typeof setTimeout> | undefined;
102
157
  #windowTimer: ReturnType<typeof setTimeout> | undefined;
103
158
  #resolveReady: () => void = () => undefined;
@@ -127,6 +182,7 @@ export class StartupReadiness {
127
182
  "holdBudgetMs",
128
183
  );
129
184
  this.#afterHolds = options.afterHolds;
185
+ this.#imageReady = options.imageReady;
130
186
  this.#readyPromise = new Promise<void>((resolve) => {
131
187
  this.#resolveReady = resolve;
132
188
  });
@@ -176,6 +232,15 @@ export class StartupReadiness {
176
232
  return [...this.#holds.values()].filter((hold) => !hold.settled).map((hold) => hold.label);
177
233
  }
178
234
 
235
+ /**
236
+ * The renderer's own wait, named for a stall report: the frame window is done and the first world frame is still
237
+ * cold. Empty before the frame window ends, after the deadline and once readiness resolves.
238
+ */
239
+ get pendingImage(): readonly string[] {
240
+ if (this.#ready || !this.#frameWindowDone || this.#imageTimedOut) return [];
241
+ return this.#imageReadiness() ? [] : ["the renderer's first world frame"];
242
+ }
243
+
179
244
  /** Completed units from active holds; settled holds freeze their count. Display progress is separate. */
180
245
  get workProgress(): number {
181
246
  let completed = 0;
@@ -285,6 +350,62 @@ export class StartupReadiness {
285
350
  }
286
351
  }
287
352
 
353
+ /**
354
+ * The renderer's answer changes only on a frame it drew, so it is polled on rendered frames and not by a
355
+ * timer: the compile and stable-window budgets must not release a picture the renderer says is cold. The
356
+ * deadline armed at the frame window is the one bound on that wait.
357
+ */
358
+ #pollImage(): void {
359
+ if (this.#ready || this.#imageReady === undefined) return;
360
+ if (this.#imageReadiness()) this.#resolveIfComplete();
361
+ }
362
+
363
+ #imageReadiness(): boolean {
364
+ return this.#imageState().ready;
365
+ }
366
+
367
+ /** The renderer's answer as a state, failing open on a read that throws, like a throwing hold. */
368
+ #imageState(): IStartupImageState {
369
+ if (this.#imageReady === undefined) return IMAGE_READY;
370
+ try {
371
+ const answer = this.#imageReady();
372
+ return typeof answer === "boolean" ? (answer ? IMAGE_READY : IMAGE_COLD) : answer;
373
+ } catch {
374
+ return IMAGE_READY;
375
+ }
376
+ }
377
+
378
+ /**
379
+ * Bound the renderer's own wait, measured from the moment the framework's work ended.
380
+ *
381
+ * Everything else in a launch is bounded by its caller; this wait is not, so a game whose opening never
382
+ * satisfies it (`STARTUP_IMAGE_TIMEOUT_MS`) would keep its cover forever. Fails open like every other launch
383
+ * wait: the line names the input that never arrived, and the world shows.
384
+ */
385
+ #armImageDeadline(): void {
386
+ if (this.#imageTimer !== undefined || this.#imageTimedOut) return;
387
+ this.#imageWaitedFrom = Date.now();
388
+ this.#imageTimer = setTimeout(() => {
389
+ this.#imageTimer = undefined;
390
+ if (this.#ready) return;
391
+ const state = this.#imageState();
392
+ // It arrived on its own inside the deadline: there is nothing to report.
393
+ if (state.ready) {
394
+ this.#resolveIfComplete();
395
+ return;
396
+ }
397
+ this.#imageTimedOut = true;
398
+ console.warn(
399
+ `TN_STARTUP_IMAGE_TIMEOUT ${JSON.stringify({
400
+ exposureSettled: state.exposureSettled === true,
401
+ shadowInputsReady: state.shadowInputsReady === true,
402
+ waitedMs: Date.now() - this.#imageWaitedFrom,
403
+ })}`,
404
+ );
405
+ this.#resolveIfComplete();
406
+ }, STARTUP_IMAGE_TIMEOUT_MS);
407
+ }
408
+
288
409
  /** Begin the one-time first-use gate after the entered scene has been built. */
289
410
  start(compile?: StartupCompile): void {
290
411
  if (this.#started) return;
@@ -307,7 +428,10 @@ export class StartupReadiness {
307
428
 
308
429
  /** Feed actual callback wall time, not requestAnimationFrame timestamp spacing. */
309
430
  observe(frameMs: number): void {
310
- if (!this.#ready) this.#pollHolds();
431
+ if (!this.#ready) {
432
+ this.#pollHolds();
433
+ this.#pollImage();
434
+ }
311
435
  if (!this.#started || this.#ready) return;
312
436
  if (
313
437
  this.#compileSettled &&
@@ -337,22 +461,33 @@ export class StartupReadiness {
337
461
  }, this.#stableWindowMs);
338
462
  }
339
463
 
340
- /** The framework's own work is done. Whether the *world* is ready also depends on the holds. */
464
+ /** The framework's own work is done. Whether the *world* is ready also depends on the holds and the picture. */
341
465
  #finishFrameWindow(): void {
342
466
  if (this.#frameWindowDone) return;
343
467
  this.#frameWindowDone = true;
344
468
  if (this.#windowTimer !== undefined) clearTimeout(this.#windowTimer);
345
469
  this.#windowTimer = undefined;
346
470
  this.#resolveFrameworkReady();
471
+ if (!this.#imageReadiness()) this.#armImageDeadline();
347
472
  this.#resolveIfComplete();
348
473
  }
349
474
 
350
475
  #resolveIfComplete(): void {
351
476
  if (this.#ready || !this.#frameWindowDone) return;
352
477
  for (const hold of this.#holds.values()) if (!hold.settled) return;
478
+ // Last, because it is the only wait that is not the caller's: a renderer that has not drawn a world a
479
+ // player may see yet keeps the cover, whatever the timers say — and no longer than its own deadline.
480
+ if (!this.#imageTimedOut && !this.#imageReadiness()) {
481
+ // A picture that was warm when the frame window closed can go cold before a game hold settles
482
+ // (a camera cut, a streamed tier): arm the deadline here too, or nothing bounds that wait.
483
+ this.#armImageDeadline();
484
+ return;
485
+ }
353
486
  // Claim readiness before awaiting, so a hold that settles during `afterHolds` cannot re-enter
354
487
  // and run it twice.
355
488
  this.#ready = true;
489
+ if (this.#imageTimer !== undefined) clearTimeout(this.#imageTimer);
490
+ this.#imageTimer = undefined;
356
491
  const afterHolds = this.#afterHolds;
357
492
  // No holds means no second tier, which means the framework's own pass already saw the whole
358
493
  // scene. Resolving synchronously there keeps every game that does not stream exactly as it was.
package/src/ui-bridge.ts CHANGED
@@ -71,6 +71,13 @@ export const UI_INTENT_MESSAGE = "tn:intent";
71
71
  * from it lies in exactly the sessions where somebody is trying to measure.
72
72
  */
73
73
  export const UI_DEV_METRICS_MESSAGE = "tn:dev-metrics";
74
+ /**
75
+ * The startup phase the game end publishes: `covered` while the loading cover is up, `ready` from
76
+ * the frame the cover lifts. The UI realm cannot read `ctx.startup`, so this is how `useUiState`
77
+ * knows to return `undefined` until the player can see the page. A game that never sends it (an
78
+ * older core) reads as uncovered.
79
+ */
80
+ export const UI_STARTUP_MESSAGE = "tn:startup";
74
81
  /**
75
82
  * The intent the UI layer sends once, when its tree has rendered and its rectangles are published.
76
83
  *
@@ -270,6 +277,36 @@ function installInbound(scope: IScope, key: string, deliver: (frame: unknown) =>
270
277
  };
271
278
  }
272
279
 
280
+ const LOOPBACK_KEY = "__tnUiLoopback";
281
+
282
+ /**
283
+ * `?tnUiLoopback=1`: both ends stay in this realm but talk over a `MessageChannel`, so every
284
+ * frame arrives a task later, the hop a game in a worker adds (PRD-752). Installed once, as the
285
+ * host globals, by whichever end connects first; the game and the UI never know.
286
+ */
287
+ function installLoopback(scope: IScope): void {
288
+ const search = (scope.location as { search?: unknown } | undefined)?.search;
289
+ if (typeof search !== "string" || new URLSearchParams(search).get("tnUiLoopback") !== "1") return;
290
+ if (scope[LOOPBACK_KEY] !== undefined) return;
291
+ const { port1: gamePort, port2: uiPort } = new MessageChannel();
292
+ const receive = (key: string) => (event: MessageEvent) =>
293
+ (scope[key] as ((frame: unknown) => void) | undefined)?.(event.data);
294
+ gamePort.onmessage = receive(UI_BRIDGE_GLOBALS.gameReceive);
295
+ uiPort.onmessage = receive(UI_BRIDGE_GLOBALS.uiReceive);
296
+ scope[UI_BRIDGE_GLOBALS.gamePost] = (frame: string) => gamePort.postMessage(frame);
297
+ scope[UI_BRIDGE_GLOBALS.uiHost] = { postMessage: (frame: string) => uiPort.postMessage(frame) };
298
+ scope.__tnUiOverlayAttached = () => true;
299
+ scope[LOOPBACK_KEY] = {
300
+ close() {
301
+ gamePort.close();
302
+ uiPort.close();
303
+ for (const key of [UI_BRIDGE_GLOBALS.gamePost, UI_BRIDGE_GLOBALS.uiHost, LOOPBACK_KEY])
304
+ scope[key] = undefined;
305
+ scope.__tnUiOverlayAttached = undefined;
306
+ },
307
+ };
308
+ }
309
+
273
310
  /**
274
311
  * Connect one end of the bridge.
275
312
  *
@@ -286,6 +323,7 @@ export function connectUiBridge(options: IConnectOptions): IUiBridge {
286
323
  throw new Error(`TN_UI_BRIDGE_END_INVALID: expected 'game' or 'ui', got '${String(end)}'.`);
287
324
  }
288
325
  const scope: IScope = options.scope ?? globalThis;
326
+ installLoopback(scope);
289
327
  const listeners = new Set<(message: IUiMessage) => void>();
290
328
  const deliver = (frame: unknown): void => {
291
329
  const message = parseFrame(frame);
@@ -125,8 +125,12 @@ function quantize(value: number): number {
125
125
  return Math.round(value * 1e5) / 1e5;
126
126
  }
127
127
 
128
- /** Events that mean "something is moving and its published rect is now a frame behind". */
129
- const TRANSITION_START = ["transitionrun", "transitionstart", "animationstart"] as const;
128
+ /**
129
+ * Events that mean "something is moving and its published rect is now a frame behind".
130
+ * `transitionrun` is deliberately absent: a browser emits it as well as `transitionstart` for the
131
+ * same transition, and only that pair balances one `transitionend`/`transitioncancel`.
132
+ */
133
+ const TRANSITION_START = ["transitionstart", "animationstart"] as const;
130
134
  const TRANSITION_END = [
131
135
  "transitionend",
132
136
  "transitioncancel",
package/src/ui-layer.ts CHANGED
@@ -26,6 +26,7 @@ export {
26
26
  UI_DEV_METRICS_MESSAGE,
27
27
  UI_INTENT_MESSAGE,
28
28
  UI_READY_INTENT,
29
+ UI_STARTUP_MESSAGE,
29
30
  type IUiBridge,
30
31
  type IUiMessage,
31
32
  type UiBridgeEnd,
package/src/ui-state.ts CHANGED
@@ -1,8 +1,10 @@
1
+ import { countDebug, debugRequested, measureDebug } from "./profiling/debug-telemetry.js";
1
2
  import {
2
3
  GAME_STATE_MESSAGE,
3
4
  type IUiBridge,
4
5
  type IUiMessage,
5
6
  UI_INTENT_MESSAGE,
7
+ UI_STARTUP_MESSAGE,
6
8
  postUiState,
7
9
  serializeUiState,
8
10
  } from "./ui-bridge.js";
@@ -46,7 +48,9 @@ export interface IUiStatePublisher {
46
48
  export interface IUiStateMirror<T> {
47
49
  /** The last state the game published, or undefined before the first frame arrives. */
48
50
  get(): T | undefined;
49
- /** Called after each accepted publication. Returns an unsubscribe function. */
51
+ /** True while the game reports its loading cover up; false before it says so and after it lifts. */
52
+ covered(): boolean;
53
+ /** Called after each accepted publication, and when the cover state changes. Returns an unsubscribe function. */
50
54
  subscribe(listener: () => void): () => void;
51
55
  /** Stop listening. */
52
56
  stop(): void;
@@ -85,6 +89,13 @@ export function publishUiState<T>(
85
89
  );
86
90
  }
87
91
  const schedule = options.schedule ?? microtask;
92
+ const debug = debugRequested();
93
+ const serialize = debug
94
+ ? (state: T): string => {
95
+ countDebug("uiSerializations", 1, "ui", "publishUiState");
96
+ return measureDebug("uiSerialize", "ui", "publishUiState", () => serializeUiState(state));
97
+ }
98
+ : serializeUiState;
88
99
  const read = (): T =>
89
100
  store.getPublishedState === undefined ? store.getState() : store.getPublishedState();
90
101
  let stopped = false;
@@ -94,12 +105,21 @@ export function publishUiState<T>(
94
105
  const send = (state: T, frame: string): void => {
95
106
  lastFrame = frame;
96
107
  postUiState(bridge, state, frame);
108
+ if (debug) {
109
+ countDebug("uiMessages", 1, "ui", "publishUiState");
110
+ countDebug(
111
+ "uiMessageBytes",
112
+ new TextEncoder().encode(frame).byteLength,
113
+ "ui",
114
+ "publishUiState",
115
+ );
116
+ }
97
117
  };
98
118
 
99
119
  const publish = (): void => {
100
120
  if (stopped) return;
101
121
  const state = read();
102
- send(state, serializeUiState(state));
122
+ send(state, serialize(state));
103
123
  };
104
124
 
105
125
  const flush = (): void => {
@@ -112,7 +132,7 @@ export function publishUiState<T>(
112
132
  // Skip a publication that would carry the bytes the UI already has. A store that writes the
113
133
  // same value every tick is common and must not become a message per tick.
114
134
  const state = read();
115
- const frame = serializeUiState(state);
135
+ const frame = serialize(state);
116
136
  if (frame === lastFrame) return;
117
137
  send(state, frame);
118
138
  };
@@ -151,7 +171,15 @@ export function subscribeUiState<T>(bridge: IUiBridge): IUiStateMirror<T> {
151
171
  }
152
172
  const listeners = new Set<() => void>();
153
173
  let current: T | undefined;
174
+ let covered = false;
154
175
  const off = bridge.onMessage((message) => {
176
+ if (message.type === UI_STARTUP_MESSAGE) {
177
+ const next = message.phase !== "ready";
178
+ if (next === covered) return;
179
+ covered = next;
180
+ for (const listener of [...listeners]) listener();
181
+ return;
182
+ }
155
183
  if (message.type !== GAME_STATE_MESSAGE) return;
156
184
  const state = message.state;
157
185
  if (typeof state !== "object" || state === null || Array.isArray(state)) {
@@ -162,6 +190,7 @@ export function subscribeUiState<T>(bridge: IUiBridge): IUiStateMirror<T> {
162
190
  });
163
191
  return {
164
192
  get: () => current,
193
+ covered: () => covered,
165
194
  subscribe(listener) {
166
195
  listeners.add(listener);
167
196
  return () => listeners.delete(listener);
package/src/version.ts CHANGED
@@ -1,2 +1,2 @@
1
1
  // Generated by scripts/generate-version.mjs - do not edit. Source: package.json.
2
- export const CORE_VERSION = "0.3.6";
2
+ export const CORE_VERSION = "0.3.8";