@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
@@ -1,5 +1,28 @@
1
1
  import { Texture, Wrapping, Object3D, AnimationClip } from 'three';
2
2
 
3
+ /**
4
+ * What a request is worth relative to the rest of the queue.
5
+ *
6
+ * `now` is a file the running scene awaits, `soon` is a `WorldCells` prefetch, and `idle` is the
7
+ * background fill. A `now` request starts at once and pauses new `soon` and `idle` starts until it
8
+ * settles, so a fill can never sit in front of the file the frame needs.
9
+ */
10
+ type AssetPriority = "now" | "soon" | "idle";
11
+ interface IAssetCacheReport {
12
+ /** False on a native host, with `reason`, or when the game passed `assets.cache: false`. */
13
+ readonly enabled: boolean;
14
+ /** Whether the browser granted persistent storage. False when it refused or could not answer. */
15
+ readonly persisted: boolean;
16
+ readonly hits: number;
17
+ readonly misses: number;
18
+ readonly bytesOnDisk: number;
19
+ readonly bytesTotal: number;
20
+ readonly filling: boolean;
21
+ /** True when the post-reveal fill is allowed (`assets.backgroundFill` and no `saveData`). */
22
+ readonly backgroundFill: boolean;
23
+ readonly reason?: string;
24
+ }
25
+
3
26
  interface IAssetLoaderOptions {
4
27
  readonly basePath?: string;
5
28
  /**
@@ -29,6 +52,39 @@ interface IAssetLoaderOptions {
29
52
  * than silently uploading decoded RGBA.
30
53
  */
31
54
  readonly renderer?: unknown;
55
+ /**
56
+ * Keep compiled asset bytes on disk between visits. On by default where the Cache API exists;
57
+ * `false` is the named override. A native host has no Cache API and reports the cache off with
58
+ * the reason "native host reads installed files", so the native load path is unchanged.
59
+ */
60
+ readonly cache?: boolean;
61
+ /**
62
+ * Download the rest of the manifest after the reveal, at idle priority. On by default;
63
+ * `false` is the named override. It stops by itself when the browser reports
64
+ * `navigator.connection.saveData`.
65
+ */
66
+ readonly backgroundFill?: boolean;
67
+ }
68
+ /** What one request is worth relative to the rest of the loader's queue. */
69
+ interface IAssetRequestOptions {
70
+ /**
71
+ * `now` for a file the running scene awaits, `soon` for a prefetch. The loader's own direct
72
+ * calls default to `now`.
73
+ */
74
+ readonly priority?: AssetPriority;
75
+ }
76
+ /** What a `prefetch` asked for and what the download produced. */
77
+ interface IAssetPrefetchProgress {
78
+ readonly requested: number;
79
+ readonly requestedBytes: number;
80
+ readonly settled: number;
81
+ /** Bytes served by the load, from disk or network; not a claim that the disk kept them. */
82
+ readonly settledBytes: number;
83
+ }
84
+ /** The cache report plus the one action a settings screen needs. */
85
+ interface IAssetCacheState extends IAssetCacheReport {
86
+ /** Delete every byte this release stored, for a "free 1.8 GB" button. */
87
+ clear(): Promise<void>;
32
88
  }
33
89
  /** The structural slice of three's `KTX2Loader` core depends on. */
34
90
  interface IKTX2LoaderLike {
@@ -52,7 +108,26 @@ interface ICompressedTextureSupport {
52
108
  /** Which pipeline served a logical path: the compile step's manifest, or the project's own files. */
53
109
  type AssetSource = "manifest" | "source";
54
110
  /** Where one settled load's bytes actually came from. */
111
+ /** One downloaded file of a load, with the size the manifest records for it. */
112
+ interface IResolvedFile {
113
+ readonly bytes: number;
114
+ readonly url: string;
115
+ }
55
116
  interface IResolvedAsset {
117
+ /**
118
+ * The manifest's size for this path, set once the load settled and the manifest named one.
119
+ * Absent for a game with no manifest, an external url, or an entry the compile step wrote
120
+ * without a size, so absent means unknown and never zero.
121
+ */
122
+ readonly bytes?: number;
123
+ /**
124
+ * Every sized file the load downloaded: its own output first, then the shared images and
125
+ * lightmaps the manifest lists for it. Set with `bytes`. Two models that share an image list
126
+ * the same url, so a byte total dedupes by url.
127
+ */
128
+ readonly files?: readonly IResolvedFile[];
129
+ /** What the load was asked for; set once the load settled. */
130
+ readonly kind?: AssetKind;
56
131
  readonly url: string;
57
132
  readonly via: AssetSource;
58
133
  }
@@ -73,7 +148,7 @@ interface ITextureOptions {
73
148
  }
74
149
  interface IAssetLoader {
75
150
  readonly compressedTextures?: ICompressedTextureSupport;
76
- model<T = unknown>(path: string): Promise<T>;
151
+ model<T = unknown>(path: string, options?: IAssetRequestOptions): Promise<T>;
77
152
  /**
78
153
  * Load a texture, optionally configured in one call.
79
154
  *
@@ -93,6 +168,23 @@ interface IAssetLoader {
93
168
  * hard-code a hashed output name, which changes on every rebuild.
94
169
  */
95
170
  resolve(path: string): Promise<readonly string[]>;
171
+ /**
172
+ * What is on disk right now: hits, misses, bytes stored and the whole release's size. A loading
173
+ * view can show "1.2 of 2.0 GB on disk" without new code, and `enabled` is false with a `reason`
174
+ * on a native host or when the game passed `assets.cache: false`.
175
+ */
176
+ readonly cache: IAssetCacheState;
177
+ /**
178
+ * Download the next scene's files to disk at `soon` priority, so its `load()` reads them back
179
+ * without a cold fetch. Stores bytes only: no decode, no GPU memory. Resolves at once on native,
180
+ * where the files are already installed, and reports how many bytes the request served.
181
+ */
182
+ prefetch(paths: readonly string[]): Promise<IAssetPrefetchProgress>;
183
+ /**
184
+ * Start the post-reveal idle fill. The engine calls this when `ctx.startup.whenReady()` settles;
185
+ * a game that drives a loader outside `defineGame` may call it after its own reveal.
186
+ */
187
+ startBackgroundFill(): Promise<void>;
96
188
  /**
97
189
  * How many loads this loader has been asked for and how many have settled (resolved or
98
190
  * rejected). A loading view reads the ratio; the runtime folds it into `ctx.startup.progress`
@@ -129,7 +221,14 @@ interface IAssetLoader {
129
221
  */
130
222
  readonly resolved: ReadonlyMap<string, IResolvedAsset>;
131
223
  clear(): void;
224
+ /**
225
+ * Final release, called by the game's teardown. Frees the decoder worker pools this loader
226
+ * owns; `clear()` stays reusable because a live game may empty its cache between levels.
227
+ * Idempotent.
228
+ */
229
+ dispose(): void;
132
230
  }
231
+ type AssetKind = "audio" | "model" | "texture";
133
232
  /**
134
233
  * Repair an exported rig whose clips are Z-mirrored against its own bind pose, in place.
135
234
  *
@@ -149,4 +248,4 @@ interface IAssetLoader {
149
248
  declare function reconcileMirroredClips(root: Object3D, clips: readonly AnimationClip[]): boolean;
150
249
  declare function createAssetLoader(options?: IAssetLoaderOptions): IAssetLoader;
151
250
 
152
- export { type IAssetLoader as I, type IAssetLoaderOptions as a, type ITextureOptions as b, createAssetLoader as c, reconcileMirroredClips as r };
251
+ export { type AssetPriority as A, type IAssetLoader as I, type IAssetLoaderOptions as a, type IAssetCacheReport as b, type IAssetCacheState as c, type IAssetPrefetchProgress as d, type IAssetRequestOptions as e, type ITextureOptions as f, createAssetLoader as g, reconcileMirroredClips as r };
@@ -1,6 +1,6 @@
1
1
  import * as three from 'three';
2
2
  import { Camera, Vector2, Vector3, Scene, OrthographicCamera } from 'three';
3
- import { I as IRendererLike } from './renderer-9yEo9hPa.js';
3
+ import { I as IRendererLike } from './renderer-rZm0hVqq.js';
4
4
 
5
5
  interface IViewportSize {
6
6
  readonly aspect: number;
@@ -1,9 +1,36 @@
1
- import { I as IAssetLoader, a as IAssetLoaderOptions } from './assets-CqvE429w.js';
2
- import { F as FramePassKind, c as IRenderPassSample, d as IFramePhaseSample, e as IPipelineCensus, I as IRendererLike, f as IRendererOptions, a as IFrameBudgetWindow, g as IFrameBudgetOptions } from './renderer-9yEo9hPa.js';
1
+ import { I as IAssetLoader, a as IAssetLoaderOptions } from './assets-YUbXa3-Y.js';
2
+ import { F as FramePassKind, c as IRenderPassSample, d as IFramePhaseSample, e as IPipelineCensus, I as IRendererLike, f as IRendererOptions, a as IFrameBudgetWindow, g as IFrameBudgetOptions } from './renderer-rZm0hVqq.js';
3
3
  import { Vector2, Vector3, Object3D, Camera, Intersection, Scene as Scene$1 } from 'three';
4
- import { V as Viewport, C as CanvasLayer, I as IViewportOptions } from './canvas-layer-C1-5CviZ.js';
4
+ import { V as Viewport, C as CanvasLayer, I as IViewportOptions } from './canvas-layer-vCtanIeB.js';
5
5
  import { StoreApi } from 'zustand/vanilla';
6
6
 
7
+ type EntitySnapshot = Record<string, Record<string, unknown> & {
8
+ tags?: string[];
9
+ }>;
10
+
11
+ declare class Registry {
12
+ #private;
13
+ add<T extends object>(name: string, entity: T): T;
14
+ get<T extends object = object>(name: string): T | undefined;
15
+ forEach(callback: (name: string, entity: object) => void): void;
16
+ remove(name: string): void;
17
+ queueFree(target: string | object): void;
18
+ sweep(): void;
19
+ clear(): void;
20
+ snapshot(): EntitySnapshot;
21
+ }
22
+
23
+ /**
24
+ * The `autoBatch` object form of the game config.
25
+ *
26
+ * `guard: "spread"` (default) checks a time-bounded slice of the merged sources each frame, so a
27
+ * change the game makes to one is seen within `guardStaleFrames` frames, which the report states.
28
+ * `guard: "everyFrame"` checks every source every frame: exact, and it costs what the report says.
29
+ */
30
+ interface IAutoBatchConfig {
31
+ readonly guard?: "spread" | "everyFrame";
32
+ }
33
+
7
34
  type ThreeNativeOrientation = "landscape" | "portrait" | "sensor";
8
35
  /** Which renderer draws a game's `src/ui/`. @see IThreeNativeConfig.ui */
9
36
  type ThreeNativeUiRenderer = "native" | "native-css" | "web";
@@ -292,6 +319,8 @@ interface IThreeNativePerformanceBudget {
292
319
  readonly maxDrawCalls?: number;
293
320
  /** Maximum nearest-rank 95th-percentile frame time in milliseconds. */
294
321
  readonly maxFrameMsP95?: number;
322
+ /** Why this profile cannot hold 60 fps; the harness requires it when `maxFrameMsP95` is above 16.7. */
323
+ readonly maxFrameMsReason?: string;
295
324
  /** Maximum renderer triangle count across every pass combined. */
296
325
  readonly maxTriangles?: number;
297
326
  /** Frame-budget floor: the median presented frame must sustain at least this many frames a second. */
@@ -909,22 +938,6 @@ interface IRandom {
909
938
  }
910
939
  declare function createRandom(seed?: number): IRandom;
911
940
 
912
- type EntitySnapshot = Record<string, Record<string, unknown> & {
913
- tags?: string[];
914
- }>;
915
-
916
- declare class Registry {
917
- #private;
918
- add<T extends object>(name: string, entity: T): T;
919
- get<T extends object = object>(name: string): T | undefined;
920
- forEach(callback: (name: string, entity: object) => void): void;
921
- remove(name: string): void;
922
- queueFree(target: string | object): void;
923
- sweep(): void;
924
- clear(): void;
925
- snapshot(): EntitySnapshot;
926
- }
927
-
928
941
  interface IRaycastOptions {
929
942
  /** Screen point in canvas pixels. Mutually exclusive with `origin` and `direction`. */
930
943
  readonly screen?: Vector2;
@@ -945,15 +958,6 @@ interface IScenePickerOptions {
945
958
  readonly scene: Object3D;
946
959
  readonly viewport: Viewport;
947
960
  }
948
- /**
949
- * Ray queries against scene geometry, accelerated by a bounding volume hierarchy that is
950
- * built on first use and rebuilt when the geometry's positions change.
951
- *
952
- * The acceleration is an implementation detail: nothing about it reaches the caller, no
953
- * `three` prototype is patched, and a game that never calls `raycast` never builds a tree.
954
- * Skinned, instanced, batched and morphed meshes fall back to the stock `three` path,
955
- * because a hierarchy over their rest positions would report hits in the wrong place.
956
- */
957
961
  declare class ScenePicker {
958
962
  #private;
959
963
  constructor(options: IScenePickerOptions);
@@ -1184,6 +1188,16 @@ interface IWarmUpOptions {
1184
1188
  * turning a convention off must not turn its measurement off.
1185
1189
  */
1186
1190
  readonly renderPasses?: boolean;
1191
+ /**
1192
+ * Runs right after every draw the warm-up makes outside the game's frame loop, so the loading
1193
+ * cover can be painted over it.
1194
+ *
1195
+ * Such a draw runs in a timer task, and the browser presents it on its own: a Wasm engine that is
1196
+ * still baking the environment presents black, and the cover flickers against it for the whole
1197
+ * bake. Painting the cover in the same task makes the presented frame the cover again. Leave it
1198
+ * unset when nothing covers the canvas.
1199
+ */
1200
+ readonly afterCoveredDraw?: () => void;
1187
1201
  /**
1188
1202
  * Also render objects the scene has hidden for that one covered render. Default `false`.
1189
1203
  *
@@ -1291,7 +1305,7 @@ interface IWarmUpRenderer {
1291
1305
  * and resolves once every requested pipeline exists, so the warm-up can wait instead of
1292
1306
  * compiling on the main thread.
1293
1307
  */
1294
- warmUpWorldPass?: (scene: Object3D, camera: Camera, targetScene?: Object3D) => void | Promise<void>;
1308
+ warmUpWorldPass?: (scene: Object3D, camera: Camera, targetScene?: Object3D, afterDraw?: () => void) => void | Promise<void>;
1295
1309
  /** The renderer's own render path, used to build every pass's pipelines once. */
1296
1310
  render?: (scene: Object3D, camera: Camera) => void;
1297
1311
  raw?: unknown;
@@ -1493,6 +1507,39 @@ interface ICtx<TState extends Record<string, unknown> = Record<string, unknown>,
1493
1507
  physics: TPhysics;
1494
1508
  }
1495
1509
 
1510
+ /** Why a file the reveal waited for shows nothing at the reveal. */
1511
+ type OffscreenReason = "hidden" | "not-placed" | "outside-view";
1512
+ interface IStartupOffscreenFile {
1513
+ readonly bytes: number;
1514
+ readonly path: string;
1515
+ readonly reason: OffscreenReason;
1516
+ }
1517
+ /**
1518
+ * What the reveal waited for, split by whether the spawn camera shows it.
1519
+ *
1520
+ * Measured, never configured: nothing here is compared with a fixed size. `warn` is a ratio of two
1521
+ * numbers from the same run (off-screen bytes against visible bytes), so no constant needs
1522
+ * revisiting when links or games change.
1523
+ */
1524
+ interface IStartupOffscreenBytes {
1525
+ /** Every sized byte the reveal waited for through `ctx.assets`. */
1526
+ readonly awaitedBytes: number;
1527
+ /** The fix, so a reader of one console line needs no other document. */
1528
+ readonly fix: string;
1529
+ /** Bytes of models with an object in view. */
1530
+ readonly visibleBytes: number;
1531
+ /** Bytes of models with no visible object in the frustum. */
1532
+ readonly offscreenBytes: number;
1533
+ /** Textures and audio: no scene object ties them to a view, so the engine does not guess. */
1534
+ readonly unattributedBytes: number;
1535
+ /** Awaited files whose size the manifest does not record, so they are in no byte count. */
1536
+ readonly unsizedFiles: number;
1537
+ /** The five largest off-screen files. */
1538
+ readonly top: readonly IStartupOffscreenFile[];
1539
+ /** Most of the wait bought nothing on screen: off-screen bytes exceed visible bytes. */
1540
+ readonly warn: boolean;
1541
+ }
1542
+
1496
1543
  type PluginCleanup = () => void;
1497
1544
  interface IGameObservationSampleRequest {
1498
1545
  readonly entities?: readonly string[];
@@ -1569,6 +1616,12 @@ interface IGamePluginRuntime {
1569
1616
  * they read are the ones the world actually has. The frame loop remains held throughout.
1570
1617
  */
1571
1618
  readonly holdStart?: (gate: Promise<void>) => Promise<void>;
1619
+ /**
1620
+ * Settles when the start scene's `load()` has finished, so its entities are registered. A runner's
1621
+ * pre-entry setup awaits it: setup names entities `load()` adds, and an async `load()` (a texture
1622
+ * or a model fetch) is still pending when the runner first attaches. Rejects when `load()` throws.
1623
+ */
1624
+ readonly startSceneLoaded?: () => Promise<void>;
1572
1625
  readonly observations: IGameRuntimeObservations;
1573
1626
  readonly tick: () => number;
1574
1627
  readonly runtimeDiagnosticsSeries?: () => readonly IRenderPerformanceSample[];
@@ -1584,8 +1637,12 @@ interface IGamePluginRuntime {
1584
1637
  * must be reported rather than inferred from a phase that cannot distinguish the two.
1585
1638
  */
1586
1639
  readonly startupCompileSettled?: () => boolean;
1640
+ /** The loading cover has lifted: the startup hand-off finished and page UI shows state. */
1641
+ readonly startupRevealed?: () => boolean;
1587
1642
  /** When the startup milestones happened, for the playtest bridge's startup observation. */
1588
1643
  readonly startupTimeline?: () => IStartupTimeline;
1644
+ /** What the reveal waited for that the spawn camera does not show; absent until the reveal. */
1645
+ readonly startupOffscreenBytes?: () => IStartupOffscreenBytes | undefined;
1589
1646
  /** The renderer-owned bounded pipeline capture, when the renderer has not been opted out. */
1590
1647
  readonly pipelineCensus?: () => IPipelineCensus;
1591
1648
  /**
@@ -1633,6 +1690,13 @@ interface IGameConfig<TState extends Record<string, unknown> = Record<string, un
1633
1690
  * assertion, because turning a convention off must not turn its measurement off.
1634
1691
  */
1635
1692
  readonly frameBudget?: IFrameBudgetOptions | false;
1693
+ /**
1694
+ * Static meshes that share a material merge into one draw once the scene has settled, on by
1695
+ * default and reported as `TN_AUTO_BATCH`. A mesh the game later moves, hides or re-materials
1696
+ * comes back at once. `false` turns the pass off; `userData.batch = "off"` on a mesh or any
1697
+ * ancestor keeps just that subtree out.
1698
+ */
1699
+ readonly autoBatch?: boolean | IAutoBatchConfig;
1636
1700
  readonly initialState?: TState;
1637
1701
  /**
1638
1702
  * The **pre-start** shader warm-up. Off by default, and that is not the same as no warm-up.
@@ -1749,8 +1813,13 @@ interface IGame<TState extends Record<string, unknown> = Record<string, unknown>
1749
1813
  readonly ui: IGameUi;
1750
1814
  /** Rebuilds the requested scene from its initial state, then merges an optional carry patch. */
1751
1815
  goto(name: string, options?: IGotoOptions<TState>): Promise<void>;
1752
- /** Boot into `name` instead of `config.start` on the next `start()`. Hot reload's restore path. */
1753
- resumeScene(name: string): void;
1816
+ /**
1817
+ * Boot into `name` instead of `config.start` on the next `start()`. Hot reload's restore path.
1818
+ * `revealed`: the session already showed its HUD, so the restarted game keeps the cover lifted.
1819
+ */
1820
+ resumeScene(name: string, options?: {
1821
+ readonly revealed?: boolean;
1822
+ }): void;
1754
1823
  start(): Promise<void>;
1755
1824
  pause(): void;
1756
1825
  resume(): void;
package/dist/hot.d.ts CHANGED
@@ -1,10 +1,10 @@
1
1
  import { a as audioRuntimeSnapshot } from './audio-DIJE5HTr.js';
2
- import { I as IGame } from './game-Jz4Fdoeb.js';
2
+ import { I as IGame } from './game-cb99J-YE.js';
3
3
  import 'three';
4
- import './assets-CqvE429w.js';
5
- import './renderer-9yEo9hPa.js';
4
+ import './assets-YUbXa3-Y.js';
5
+ import './renderer-rZm0hVqq.js';
6
6
  import 'three/webgpu';
7
- import './canvas-layer-C1-5CviZ.js';
7
+ import './canvas-layer-vCtanIeB.js';
8
8
  import 'zustand/vanilla';
9
9
 
10
10
  interface IHotDiagnostics {
package/dist/hot.js CHANGED
@@ -1,5 +1,15 @@
1
1
  import 'three';
2
2
 
3
+ // src/audio.ts
4
+
5
+ // src/platform.ts
6
+ function hostWindow() {
7
+ return typeof window === "undefined" ? void 0 : window;
8
+ }
9
+ function hostDocument() {
10
+ return typeof document === "undefined" ? void 0 : document;
11
+ }
12
+
3
13
  // src/audio.ts
4
14
  var AUDIO_STATE = /* @__PURE__ */ Symbol.for("threenative.audio.runtime");
5
15
  function audioState() {
@@ -46,14 +56,17 @@ function acceptHotUpdate(game, hot) {
46
56
  const carried = hot.data.threenative;
47
57
  const reloads = carried?.reloads ?? 0;
48
58
  if (carried !== void 0) restoreState(game, carried.state);
59
+ let revealed = false;
49
60
  if (carried?.sceneName !== void 0) {
50
61
  try {
51
- game.resumeScene(carried.sceneName);
62
+ game.resumeScene(carried.sceneName, { revealed: carried.revealed === true });
63
+ revealed = carried.revealed === true;
52
64
  } catch {
53
65
  }
54
66
  }
55
- if (isDev && typeof window !== "undefined") {
56
- const host = window;
67
+ const page = hostWindow();
68
+ if (isDev && page !== void 0) {
69
+ const host = page;
57
70
  host.__THREENATIVE__ = {
58
71
  ...host.__THREENATIVE__,
59
72
  hot: () => diagnostics(game, reloads),
@@ -68,7 +81,12 @@ function acceptHotUpdate(game, hot) {
68
81
  game.state.flush();
69
82
  const state = game.state.getState();
70
83
  assertPortableState(state);
71
- data.threenative = { reloads: reloads + 1, sceneName: game.sceneName, state };
84
+ data.threenative = {
85
+ reloads: reloads + 1,
86
+ revealed: revealed || game.ctx?.startup.phase === "ready",
87
+ sceneName: game.sceneName,
88
+ state
89
+ };
72
90
  } catch (error) {
73
91
  data.threenative = void 0;
74
92
  hot.invalidate(error instanceof Error ? error.message : String(error));
@@ -104,7 +122,7 @@ function diagnostics(game, reloads) {
104
122
  reloads,
105
123
  entities: ctx === void 0 ? 0 : Object.keys(ctx.entities.snapshot()).length,
106
124
  sceneObjects,
107
- canvases: typeof document === "undefined" ? 0 : document.querySelectorAll("canvas").length,
125
+ canvases: hostDocument()?.querySelectorAll("canvas").length ?? 0,
108
126
  audio: audioRuntimeSnapshot(),
109
127
  physics: typeof physics?.numBodies === "function" ? physics.numBodies() : null
110
128
  };