@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
package/src/worker.ts CHANGED
@@ -711,6 +711,7 @@ export function startWorkerGame(
711
711
  }
712
712
  };
713
713
 
714
+ let started = false;
714
715
  let resolveReady: () => void = () => undefined;
715
716
  let rejectReady: (error: Error) => void = () => undefined;
716
717
  const ready = new Promise<void>((resolve, reject) => {
@@ -789,6 +790,7 @@ export function startWorkerGame(
789
790
  installMirror(message.name, message.epoch);
790
791
  break;
791
792
  case "tn-worker-started":
793
+ started = true;
792
794
  resolveReady();
793
795
  break;
794
796
  case "tn-worker-failed":
@@ -833,8 +835,16 @@ export function startWorkerGame(
833
835
 
834
836
  listen(worker, "message", onWorkerMessage);
835
837
  const onWorkerError = (event: Event): void => {
836
- const message = (event as ErrorEvent).message;
837
- stop(new Error(message || `TN_WORKER_FAILED: worker ${event.type}.`));
838
+ // A worker's ErrorEvent carries where it threw; without it the page sees only the message, and a
839
+ // stack-less "worker died" is unactionable (the 0.3.13 release proof lost a red this way).
840
+ const error = event as ErrorEvent;
841
+ const origin = [error.filename, error.lineno, error.colno].filter(Boolean).join(":");
842
+ const message = `${error.message || `worker ${event.type}`}${origin ? ` (${origin})` : ""}`;
843
+ // Once started, nothing awaits `ready`: without this line a frame that threw removed the canvas
844
+ // and printed nothing (PRD-857).
845
+ if (started && !stopped)
846
+ console.error(`TN_WORKER_FAILED: the running worker game stopped: ${message}`);
847
+ stop(new Error(message));
838
848
  };
839
849
  listen(worker, "error", onWorkerError);
840
850
  listen(worker, "messageerror", onWorkerError);
@@ -1,4 +1,4 @@
1
- import type { Material, Mesh } from "three";
1
+ import { type Material, type Mesh, Object3D } from "three";
2
2
  import { isEngineRenderHook } from "./engine-render-hook.js";
3
3
 
4
4
  /**
@@ -69,9 +69,16 @@ const BUNDLE_PROOF_ROWS_PER_FRAME = 256;
69
69
  */
70
70
  const BUNDLE_PROOF_MAX_PERIOD = 600;
71
71
 
72
+ /** The owned engine's witness of each proved material's surface flags (PRD-879). */
73
+ interface IMaterialWitnessHost {
74
+ __tnMaterialWatch?(materials: readonly Material[]): number;
75
+ __tnMaterialCheck?(): ArrayLike<number>;
76
+ }
77
+
72
78
  /** Own-link and installed-Node child snapshots avoid inherited TSL method scans. Deep unversioned
73
79
  * edits still invalidate: version/root identity alone cannot certify a mutable node graph. The
74
- * shallow witness (version, transparency, visibility, transmission) is read on every check. The deep
80
+ * shallow witness (version, transparency, visibility, transmission) holds on every check: read per
81
+ * check, or for a `deep: false` check the flags are the owned engine's one answer a frame. The deep
75
82
  * rows are proved once per `staleFrames` period: the rows the last frame tested over a per-frame
76
83
  * budget, so a small world proves every frame and a forest spreads its proofs evenly, each material
77
84
  * in its own slot of the period. Three itself rebuilds a draw only when `material.version` moves
@@ -79,6 +86,16 @@ const BUNDLE_PROOF_MAX_PERIOD = 600;
79
86
  * window. A graph past the witness caps uses the uncached safety walk. */
80
87
  export class BundleSurfaceSafety {
81
88
  #checks = new WeakMap<Material, IBundleMaterialCheck>();
89
+ /**
90
+ * The owned engine holds every cached verdict's `transparent`, `visible` and `transmission` and
91
+ * answers which moved in one call a frame, so a settled `deep: false` test reads none of them.
92
+ * Upstream three has no such host method and reads them per test, as before.
93
+ *
94
+ * ponytail: the list keeps every proved material until `clear`, which a world bounds by its assets.
95
+ */
96
+ readonly #witness = new Object3D() as Object3D & IMaterialWitnessHost;
97
+ #witnessed: Material[] = [];
98
+ readonly #moved = new Set<Material>();
82
99
  #revision = 0;
83
100
  #frame = 0;
84
101
  #frameRows = 0;
@@ -93,6 +110,9 @@ export class BundleSurfaceSafety {
93
110
 
94
111
  clear(): void {
95
112
  this.#checks = new WeakMap();
113
+ this.#witnessed = [];
114
+ this.#moved.clear();
115
+ this.#witness.__tnMaterialWatch?.(this.#witnessed);
96
116
  }
97
117
 
98
118
  /** Opens a frame: the period every deep proof is spread over follows the last frame's rows. */
@@ -103,6 +123,12 @@ export class BundleSurfaceSafety {
103
123
  Math.max(1, Math.ceil(this.#frameRows / BUNDLE_PROOF_ROWS_PER_FRAME)),
104
124
  );
105
125
  this.#frameRows = 0;
126
+ // A moved material stays moved until its next test re-proves it, because that re-proof
127
+ // re-stamps the whole list and the engine would not answer for it again.
128
+ const moved = this.#witness.__tnMaterialCheck?.();
129
+ if (moved !== undefined)
130
+ for (let at = 0; at < moved.length; at++)
131
+ this.#moved.add(this.#witnessed[moved[at] as number] as Material);
106
132
  }
107
133
 
108
134
  /**
@@ -114,13 +140,7 @@ export class BundleSurfaceSafety {
114
140
  test(material: Material, deep = true): IBundleMaterialCheck {
115
141
  this.stats.checks++;
116
142
  const previous = this.#checks.get(material);
117
- if (
118
- previous !== undefined &&
119
- previous.version === material.version &&
120
- previous.transparent === material.transparent &&
121
- previous.visible === material.visible &&
122
- previous.transmission === Reflect.get(material, "transmission")
123
- ) {
143
+ if (previous !== undefined && this.#shallowHolds(material, previous, deep)) {
124
144
  if (!deep) return previous;
125
145
  if (previous.testedFrame !== this.#frame) {
126
146
  previous.testedFrame = this.#frame;
@@ -157,9 +177,34 @@ export class BundleSurfaceSafety {
157
177
  if (capture.overflow) {
158
178
  this.stats.uncached++;
159
179
  this.#checks.delete(material);
160
- } else this.#checks.set(material, checked);
180
+ } else {
181
+ this.#checks.set(material, checked);
182
+ this.#rewatch(material);
183
+ }
161
184
  return checked;
162
185
  }
186
+
187
+ /**
188
+ * Whether the material still holds the cached verdict's shallow witness. `version` is JS-side;
189
+ * the flags are the engine's answer when it witnesses them and a `deep: false` test asks.
190
+ */
191
+ #shallowHolds(material: Material, previous: IBundleMaterialCheck, deep: boolean): boolean {
192
+ if (previous.version !== material.version) return false;
193
+ if (!deep && this.#witness.__tnMaterialCheck !== undefined) return !this.#moved.has(material);
194
+ return (
195
+ previous.transparent === material.transparent &&
196
+ previous.visible === material.visible &&
197
+ previous.transmission === Reflect.get(material, "transmission")
198
+ );
199
+ }
200
+
201
+ /** Re-stamp the engine's witness after a verdict was (re)taken, so it answers from this state. */
202
+ #rewatch(material: Material): void {
203
+ if (this.#witness.__tnMaterialWatch === undefined) return;
204
+ if (!this.#witnessed.includes(material)) this.#witnessed.push(material);
205
+ this.#moved.delete(material);
206
+ this.#witness.__tnMaterialWatch(this.#witnessed);
207
+ }
163
208
  }
164
209
 
165
210
  function graphSnapshotCurrent(row: IBundleGraphSnapshot): boolean {