@threenative/core 0.3.12 → 0.3.15

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 (165) hide show
  1. package/README.md +1 -1
  2. package/capabilities.json +1047 -44
  3. package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
  4. package/dist/{canvas-layer-CWuFRT7G.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
  5. package/dist/{chunk-7UUT3TY5.js → chunk-2GPHICV6.js} +1 -1
  6. package/dist/{chunk-GMHATRPW.js → chunk-GEMQJBY4.js} +1650 -383
  7. package/dist/{chunk-VAZM36TV.js → chunk-H4J6IAJE.js} +17 -10
  8. package/dist/{chunk-5O73CDMR.js → chunk-QAMSM3Z5.js} +415 -27
  9. package/dist/{chunk-2Z44XSI2.js → chunk-QAQHYOWY.js} +3 -7
  10. package/dist/{chunk-DBELTTTM.js → chunk-U4YHUKKL.js} +1 -1
  11. package/dist/{chunk-OKXUCASC.js → chunk-VBBYWGAT.js} +3 -4
  12. package/dist/chunk-VP43GIWW.js +18 -0
  13. package/dist/{chunk-N5LRP4BR.js → chunk-VQRPEOKY.js} +66 -3
  14. package/dist/{chunk-6KLNISRJ.js → chunk-XDTZ4QMO.js} +11 -4
  15. package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
  16. package/dist/{game-D7pAzZUY.d.ts → game-k8K3hZai.d.ts} +72 -8
  17. package/dist/hot.d.ts +5 -4
  18. package/dist/hot.js +5 -8
  19. package/dist/index.d.ts +871 -1018
  20. package/dist/index.js +4786 -1631
  21. package/dist/{model-lod-B6BMqS1r.d.ts → model-lod-DPTzeCcD.d.ts} +4 -2
  22. package/dist/playtest.d.ts +5 -4
  23. package/dist/playtest.js +6 -5
  24. package/dist/quality-BADStsTn.d.ts +868 -0
  25. package/dist/react.d.ts +3 -2
  26. package/dist/render-environment.d.ts +170 -0
  27. package/dist/render-environment.js +352 -0
  28. package/dist/{renderer-DvFVoAgj.d.ts → renderer-BtOSseYf.d.ts} +29 -31
  29. package/dist/spells/index.js +1 -1
  30. package/dist/ui-layer.js +3 -2
  31. package/dist/worker.js +12 -5
  32. package/dist/world.d.ts +280 -16
  33. package/dist/world.js +1529 -642
  34. package/mcp/animation-server.mjs +1 -1
  35. package/mcp/engine-server.mjs +135 -11
  36. package/mcp/servers.mjs +4 -4
  37. package/package.json +10 -6
  38. package/scripts/ensure-mcp.mjs +6 -1
  39. package/src/animation-batch.ts +193 -0
  40. package/src/animation-layers.ts +7 -3
  41. package/src/animation.ts +209 -29
  42. package/src/asset-cache.ts +3 -3
  43. package/src/asset-memo.ts +202 -0
  44. package/src/assets.ts +436 -131
  45. package/src/auto-batch.ts +190 -44
  46. package/src/clustered-batch.ts +146 -3
  47. package/src/clustered-mesh.ts +548 -20
  48. package/src/compute-driven.ts +1 -1
  49. package/src/config.ts +8 -0
  50. package/src/debug.ts +119 -22
  51. package/src/dev-global.ts +54 -0
  52. package/src/displaced-surface.ts +428 -0
  53. package/src/engine-hooks.ts +37 -0
  54. package/src/frame-budget.ts +35 -3
  55. package/src/game-boot-phase.ts +269 -0
  56. package/src/game-dev-tools.ts +7 -14
  57. package/src/game-frame-loop.ts +45 -82
  58. package/src/game-startup.ts +145 -70
  59. package/src/game-ui.ts +84 -0
  60. package/src/game.ts +168 -552
  61. package/src/gamepad-mappings.ts +269 -0
  62. package/src/generated/console-markers.ts +14 -0
  63. package/src/geometry-capture.ts +28 -4
  64. package/src/gpu-readings.ts +98 -0
  65. package/src/gpu-scene-bvh.ts +149 -36
  66. package/src/grass-field.ts +628 -0
  67. package/src/hot.ts +4 -7
  68. package/src/index.ts +227 -8
  69. package/src/input.ts +237 -25
  70. package/src/instanced-batch-lod.ts +3 -8
  71. package/src/interpolation.ts +171 -40
  72. package/src/look/ao-admission.ts +4 -3
  73. package/src/look/auto-exposure.ts +5 -16
  74. package/src/look/default-tone-mapping.ts +41 -5
  75. package/src/look/local-exposure.ts +2 -7
  76. package/src/look/quad-pass.ts +21 -0
  77. package/src/look/quality.ts +4 -0
  78. package/src/look/unreal-bloom.ts +4 -13
  79. package/src/look/world-environment.ts +58 -115
  80. package/src/merge-parts.ts +20 -24
  81. package/src/model-lod.ts +97 -14
  82. package/src/particle-significance.ts +12 -0
  83. package/src/particles.ts +19 -10
  84. package/src/platform.ts +23 -4
  85. package/src/profiling/FrameStages.ts +5 -6
  86. package/src/profiling/Spans.ts +3 -17
  87. package/src/profiling/debug-telemetry.ts +2 -6
  88. package/src/profiling/render-list-validate.ts +6 -15
  89. package/src/projection-marker.ts +2 -1
  90. package/src/quiet-markers.ts +3 -10
  91. package/src/render/cpu-bvh.ts +100 -0
  92. package/src/render/depth-pyramid.ts +6 -14
  93. package/src/render/environment/environmentContribution.ts +202 -0
  94. package/src/render/environment/environmentRadiance.ts +44 -0
  95. package/src/render/environment/environmentSampleCache.ts +56 -0
  96. package/src/render/environment/environmentSampling.ts +201 -0
  97. package/src/render/environment/environmentSnapshot.ts +71 -0
  98. package/src/render/environment/gate.ts +57 -0
  99. package/src/render/material-key.ts +21 -1
  100. package/src/render/mesh-pool.ts +3 -19
  101. package/src/render/probe-trace.ts +872 -0
  102. package/src/render/probe-volume.ts +780 -34
  103. package/src/render/radiance-cache.ts +17 -0
  104. package/src/render/screen-probe-gather.ts +303 -0
  105. package/src/render/short-range-ao.ts +274 -0
  106. package/src/render/virtual-shadow-partial.ts +13 -0
  107. package/src/render/virtual-shadow.ts +18 -16
  108. package/src/render/world-impostor-surface.ts +207 -9
  109. package/src/render/world-impostor.ts +5 -2
  110. package/src/render-camera-cull.ts +105 -4
  111. package/src/render-environment.ts +41 -0
  112. package/src/renderer-config.ts +36 -0
  113. package/src/renderer-facts.ts +37 -0
  114. package/src/renderer.ts +78 -32
  115. package/src/resolution-scaler.ts +3 -2
  116. package/src/scatter-field.ts +496 -0
  117. package/src/scene-entry-inspectors.ts +61 -0
  118. package/src/snow-field.ts +1 -0
  119. package/src/startup-offscreen-bytes.ts +84 -0
  120. package/src/state.ts +16 -3
  121. package/src/static-transform.ts +100 -25
  122. package/src/streamed-textures.ts +112 -0
  123. package/src/streaming.ts +68 -4
  124. package/src/texture-streaming.ts +331 -0
  125. package/src/tile-ring.ts +294 -0
  126. package/src/version.ts +1 -1
  127. package/src/warmup.ts +15 -2
  128. package/src/worker.ts +12 -2
  129. package/src/world-bundle-safety.ts +55 -10
  130. package/src/world-cell-batches.ts +166 -200
  131. package/src/world-cell-chunks.ts +3 -7
  132. package/src/world-cell-data.ts +7 -0
  133. package/src/world-cell-impostors.ts +20 -8
  134. package/src/world-cell-models.ts +36 -8
  135. package/src/world-cell-options.ts +2 -14
  136. package/src/world-cell-placements.ts +194 -90
  137. package/src/world-cell-prewarm.ts +39 -4
  138. package/src/world-cell-records.ts +401 -0
  139. package/src/world-cell-render-bundles.ts +2 -2
  140. package/src/world-cell-render-gpu-dress.ts +17 -19
  141. package/src/world-cell-render-main-cull.ts +73 -17
  142. package/src/world-cell-render-util.ts +18 -5
  143. package/src/world-cell-render.ts +13 -5
  144. package/src/world-cell-residency.ts +15 -6
  145. package/src/world-cell-stale.ts +238 -0
  146. package/src/world-cells.ts +23 -6
  147. package/src/world-gpu-flags.ts +18 -50
  148. package/src/world-gpu-reference.ts +22 -8
  149. package/src/world-gpu-scene.ts +44 -24
  150. package/src/world-gpu-shadow.ts +21 -8
  151. package/src/world-gpu-types.ts +41 -13
  152. package/src/world-load-limiter.ts +5 -0
  153. package/src/world-model-sections.ts +80 -0
  154. package/src/world-river-ribbon.ts +273 -0
  155. package/src/world-root-frame.ts +39 -0
  156. package/src/world-shore-field.ts +91 -0
  157. package/src/world-static-pose.ts +163 -0
  158. package/src/world-surface-sampler.ts +48 -0
  159. package/src/world-terrain-splat.ts +10 -18
  160. package/src/world-tile-budget.ts +4 -11
  161. package/src/world-tiles.ts +79 -12
  162. package/src/world-validate.ts +6 -14
  163. package/src/world-warm.ts +51 -0
  164. package/src/world-water-bodies.ts +113 -3
  165. package/src/world.ts +13 -0
@@ -23,6 +23,25 @@ interface IAssetCacheReport {
23
23
  readonly reason?: string;
24
24
  }
25
25
 
26
+ /**
27
+ * Generated content kept between runs (PRD-860): `ctx.assets.memo(key, build)` returns what `build`
28
+ * returned the last time this exact build of the game ran, read back from disk, and calls `build`
29
+ * only when nothing is stored. A seeded world, a painted sky or a baked placement list is the same
30
+ * every run of one build, so a repeat visit stops paying for it.
31
+ *
32
+ * The value is named typed arrays, the shape a generator hands to geometry, instancing and
33
+ * textures. The build identity is the hashed entry script the web build writes into the page
34
+ * (`__TN_BUILD_ID__`), so any code change regenerates and the old build's entries are deleted. With
35
+ * no build identity (the dev server) or no Cache API (a native host), `build` runs every time and
36
+ * `TN_ASSET_MEMO` says why.
37
+ */
38
+ type MemoArray = Float32Array | Float64Array | Int8Array | Int16Array | Int32Array | Uint8Array | Uint8ClampedArray | Uint16Array | Uint32Array;
39
+ /** Every field a typed array: a record or an interface, which has no index signature. */
40
+ type MemoShape<T> = {
41
+ readonly [K in keyof T]: MemoArray;
42
+ };
43
+ type AssetMemo = <T extends MemoShape<T>>(key: string, build: () => T | Promise<T>) => Promise<T>;
44
+
26
45
  interface IAssetLoaderOptions {
27
46
  readonly basePath?: string;
28
47
  /**
@@ -64,14 +83,46 @@ interface IAssetLoaderOptions {
64
83
  * `navigator.connection.saveData`.
65
84
  */
66
85
  readonly backgroundFill?: boolean;
86
+ /**
87
+ * Draw a model's coarse companion first, where the cook wrote one, and the full model when it
88
+ * lands (PRD-860). On by default; `false` is the named override, reported once as
89
+ * `TN_ASSETS_STREAM_MESHES_OFF`.
90
+ */
91
+ readonly streamMeshes?: boolean;
92
+ /**
93
+ * Draw a streamed model's KTX2 textures with their resident mips first, and the whole files when
94
+ * they land (PRD-860). On by default; `false` is the named override, reported once as
95
+ * `TN_ASSETS_STREAM_TEXTURES_OFF`. It rides on `streamMeshes`: the coarse parse is where the
96
+ * resident mips draw.
97
+ */
98
+ readonly streamTextures?: boolean;
67
99
  }
68
100
  /** What one request is worth relative to the rest of the loader's queue. */
101
+ /**
102
+ * Report marker for a file a scene asks for after the reveal that the game had not prefetched.
103
+ *
104
+ * The reveal is the first moment the player is playing, so the download such a request starts is
105
+ * time spent looking at a world without that file in it — the pop-in a streaming game exists to
106
+ * avoid. One line per file, carrying the bytes and how far into play the request landed, so a
107
+ * playtest can count the pop-ins instead of a person having to watch for them.
108
+ *
109
+ * A file the game asked `prefetch` for first is not late: that is a deliberate stream, and the
110
+ * engine's own background fill is no promise either — it lags the link by design.
111
+ */
112
+ declare const ASSET_LATE_MARKER = "TN_ASSET_LATE";
69
113
  interface IAssetRequestOptions {
70
114
  /**
71
115
  * `now` for a file the running scene awaits, `soon` for a prefetch. The loader's own direct
72
116
  * calls default to `now`.
73
117
  */
74
118
  readonly priority?: AssetPriority;
119
+ /**
120
+ * PRD-860: `true` resolves a model only once its full file has replaced the coarse companion the
121
+ * first scene draws (the same object, upgraded in place). For a caller that copies the vertices:
122
+ * a trimesh or convex-hull collider, a navmesh bake, a geometry merge. Default: the coarse model,
123
+ * so the scene plays before the download ends.
124
+ */
125
+ readonly whole?: boolean;
75
126
  }
76
127
  /** What a `prefetch` asked for and what the download produced. */
77
128
  interface IAssetPrefetchProgress {
@@ -183,8 +234,22 @@ interface IAssetLoader {
183
234
  /**
184
235
  * Start the post-reveal idle fill. The engine calls this when `ctx.startup.whenReady()` settles;
185
236
  * a game that drives a loader outside `defineGame` may call it after its own reveal.
237
+ *
238
+ * It is also where the reveal is marked for {@link ASSET_LATE_MARKER}: a whole-file load a scene
239
+ * asks for after this call, and that the game did not `prefetch`, is reported as the pop-in it is.
240
+ * A game that never calls it never gets the report.
186
241
  */
187
242
  startBackgroundFill(): Promise<void>;
243
+ /**
244
+ * Generated content kept between runs (PRD-860): returns what `build` returned the last time this
245
+ * build of the game ran, read from disk, and calls `build` only when nothing is stored. Use it for
246
+ * seeded work that is the same every run, such as placement lists, painted sky pixels or terrain
247
+ * heights. The value is named typed arrays. A new build regenerates. On the dev server and on a
248
+ * native host `build` runs every time, and `TN_ASSET_MEMO` says why.
249
+ *
250
+ * @example const { pixels } = await ctx.assets.memo("sky", () => ({ pixels: paintSky() }));
251
+ */
252
+ memo: AssetMemo;
188
253
  /**
189
254
  * How many loads this loader has been asked for and how many have settled (resolved or
190
255
  * rejected). A loading view reads the ratio; the runtime folds it into `ctx.startup.progress`
@@ -247,5 +312,17 @@ type AssetKind = "audio" | "model" | "texture";
247
312
  */
248
313
  declare function reconcileMirroredClips(root: Object3D, clips: readonly AnimationClip[]): boolean;
249
314
  declare function createAssetLoader(options?: IAssetLoaderOptions): IAssetLoader;
315
+ /**
316
+ * Fetch a data file the asset loader serves: each url `assets.resolve(path)` names, in order, until
317
+ * one answers ok. A built game serves the hashed output and a dev server the source path, so taking
318
+ * only the first url 404s on one of them. When none answers it throws `TN_ASSET_NOT_SERVED` naming
319
+ * every url tried and why, so a missing file is never a half-drawn world.
320
+ *
321
+ * @situation load a baked JSON or binary file (a heightmap, a placement buffer, a data table) that the loader has no typed method for
322
+ * @situation a data file loads in dev but 404s in the built game
323
+ * @constraint reads the response once; call `.json()` or `.arrayBuffer()` on the result
324
+ * @example const heights = new Float32Array(await (await fetchAsset(ctx.assets, "world/forest.bin")).arrayBuffer());
325
+ */
326
+ declare function fetchAsset(assets: Pick<IAssetLoader, "resolve">, path: string): Promise<Response>;
250
327
 
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 };
328
+ export { ASSET_LATE_MARKER as A, type IAssetLoader as I, type IAssetLoaderOptions as a, type AssetPriority as b, type IAssetCacheReport as c, type IAssetCacheState as d, type IAssetPrefetchProgress as e, type IAssetRequestOptions as f, type ITextureOptions as g, createAssetLoader as h, fetchAsset as i, 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-DvFVoAgj.js';
3
+ import { I as IRendererLike } from './renderer-BtOSseYf.js';
4
4
 
5
5
  interface IViewportSize {
6
6
  readonly aspect: number;
@@ -1,4 +1,4 @@
1
- import { debugRequested, countDebug, measureDebug } from './chunk-N5LRP4BR.js';
1
+ import { debugRequested, countDebug, measureDebug } from './chunk-VQRPEOKY.js';
2
2
  import { UI_STARTUP_MESSAGE, GAME_STATE_MESSAGE, UI_INTENT_MESSAGE, postUiState, serializeUiState } from './chunk-CFGTPFUH.js';
3
3
 
4
4
  // src/ui-state.ts