@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
package/src/viewport.ts CHANGED
@@ -7,6 +7,7 @@ import {
7
7
  Vector2,
8
8
  Vector3,
9
9
  } from "three";
10
+ import { hostDocument, hostWindow } from "./platform.js";
10
11
  import { type IRendererLike, observeCanvasResize, readCanvasSize } from "./renderer.js";
11
12
 
12
13
  export interface IViewportSize {
@@ -198,9 +199,11 @@ function nativeInsets(): IViewportInsets | undefined {
198
199
  }
199
200
 
200
201
  function browserInsets(): IViewportInsets | undefined {
201
- if (typeof document === "undefined" || typeof window === "undefined") return undefined;
202
- if (typeof window.getComputedStyle !== "function") return undefined;
203
- const probe = document.createElement("div");
202
+ const page = hostDocument();
203
+ const view = hostWindow();
204
+ if (page === undefined || view === undefined) return undefined;
205
+ if (typeof view.getComputedStyle !== "function") return undefined;
206
+ const probe = page.createElement("div");
204
207
  probe.style.cssText = [
205
208
  "position:fixed",
206
209
  "inset:0",
@@ -215,10 +218,10 @@ function browserInsets(): IViewportInsets | undefined {
215
218
  // computed padding to the empty string, which parses to zero — four zeroes indistinguishable
216
219
  // from a device that genuinely has no insets, reported as `measured`. The full-drawable
217
220
  // fallback is the honest answer when there was no measurement to take.
218
- const body = document.body;
221
+ const body = page.body;
219
222
  if (body === null || body === undefined) return undefined;
220
223
  body.appendChild(probe);
221
- const style = window.getComputedStyle(probe);
224
+ const style = view.getComputedStyle(probe);
222
225
  const value = {
223
226
  bottom: Number.parseFloat(style.paddingBottom) || 0,
224
227
  left: Number.parseFloat(style.paddingLeft) || 0,
package/src/warmup.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import type { Camera, Object3D, Texture } from "three";
2
2
  import { pmremTexture } from "three/tsl";
3
3
 
4
+ import { isAutoBatchSource } from "./auto-batch.js";
4
5
  import type { IPipelineCensus } from "./pipeline-census.js";
5
6
  import { STARTUP_HOLD_BUDGET_MS } from "./startup-readiness.js";
6
7
 
@@ -124,6 +125,16 @@ export interface IWarmUpOptions {
124
125
  * turning a convention off must not turn its measurement off.
125
126
  */
126
127
  readonly renderPasses?: boolean;
128
+ /**
129
+ * Runs right after every draw the warm-up makes outside the game's frame loop, so the loading
130
+ * cover can be painted over it.
131
+ *
132
+ * Such a draw runs in a timer task, and the browser presents it on its own: a Wasm engine that is
133
+ * still baking the environment presents black, and the cover flickers against it for the whole
134
+ * bake. Painting the cover in the same task makes the presented frame the cover again. Leave it
135
+ * unset when nothing covers the canvas.
136
+ */
137
+ readonly afterCoveredDraw?: () => void;
127
138
  /**
128
139
  * Also render objects the scene has hidden for that one covered render. Default `false`.
129
140
  *
@@ -239,6 +250,7 @@ export interface IWarmUpRenderer {
239
250
  scene: Object3D,
240
251
  camera: Camera,
241
252
  targetScene?: Object3D,
253
+ afterDraw?: () => void,
242
254
  ) => void | Promise<void>;
243
255
  /** The renderer's own render path, used to build every pass's pipelines once. */
244
256
  render?: (scene: Object3D, camera: Camera) => void;
@@ -252,7 +264,12 @@ interface IPMREMNodeClass {
252
264
 
253
265
  /** The native engine's facade bakes the environment itself; warm-up draws the held scene until it is done. */
254
266
  interface INativeEnvironmentPreparer {
255
- prepareEnvironmentAsync(scene: Object3D, camera: Camera, deadlineMs: number): Promise<boolean>;
267
+ prepareEnvironmentAsync(
268
+ scene: Object3D,
269
+ camera: Camera,
270
+ deadlineMs: number,
271
+ afterDraw?: () => void,
272
+ ): Promise<boolean>;
256
273
  }
257
274
 
258
275
  function nativeEnvironmentPreparer(raw: unknown): INativeEnvironmentPreparer | undefined {
@@ -262,7 +279,10 @@ function nativeEnvironmentPreparer(raw: unknown): INativeEnvironmentPreparer | u
262
279
  : undefined;
263
280
  }
264
281
 
265
- function sceneNeedsEnvironmentPreparation(renderer: IWarmUpRenderer, scene: Object3D): boolean {
282
+ export function sceneNeedsEnvironmentPreparation(
283
+ renderer: IWarmUpRenderer,
284
+ scene: Object3D,
285
+ ): boolean {
266
286
  const environment = (scene as Object3D & { environment?: Texture }).environment;
267
287
  if (environment?.isTexture !== true) return false;
268
288
 
@@ -273,11 +293,12 @@ function sceneNeedsEnvironmentPreparation(renderer: IWarmUpRenderer, scene: Obje
273
293
  return backend?.isWebGPUBackend === true;
274
294
  }
275
295
 
276
- async function prepareSceneEnvironment(
296
+ export async function prepareSceneEnvironment(
277
297
  renderer: IWarmUpRenderer,
278
298
  scene: Object3D,
279
299
  camera: Camera,
280
300
  deadlineMs: number,
301
+ afterDraw?: () => void,
281
302
  ): Promise<boolean> {
282
303
  const environment = (scene as Object3D & { environment?: Texture }).environment;
283
304
  if (environment?.isTexture !== true) return true;
@@ -285,7 +306,8 @@ async function prepareSceneEnvironment(
285
306
  const raw = renderer.raw;
286
307
  if (typeof raw !== "object" || raw === null) return true;
287
308
  const native = nativeEnvironmentPreparer(raw);
288
- if (native !== undefined) return native.prepareEnvironmentAsync(scene, camera, deadlineMs);
309
+ if (native !== undefined)
310
+ return native.prepareEnvironmentAsync(scene, camera, deadlineMs, afterDraw);
289
311
  const backend = (raw as { backend?: { isWebGPUBackend?: boolean } }).backend;
290
312
  if (backend?.isWebGPUBackend !== true) return true;
291
313
 
@@ -296,7 +318,30 @@ async function prepareSceneEnvironment(
296
318
  "TN_PMREM_ASYNC_PREPARER_UNAVAILABLE: patched Three.js has no PMREM cache preparer.",
297
319
  );
298
320
  }
299
- return prepare.call(PMREMNode, raw, environment);
321
+ // False at the deadline, as the native preparer does; the bake keeps running. Unbounded, an Action
322
+ // RPG restart on 2-CPU SwiftShader waited the whole sky bake (about 30 s) with no frame drawn.
323
+ const prepared = prepare.call(PMREMNode, raw, environment);
324
+ // The deadline below ends this wait, not the bake: the world draws without the environment's fill
325
+ // until the bake lands. Say when it does, so a harness (engine parity) can photograph the settled
326
+ // frame instead of the one before it.
327
+ console.info("TN_ENVIRONMENT_BAKE:started");
328
+ void prepared.then(
329
+ (ready) => console.info(`TN_ENVIRONMENT_BAKE:finished ready=${ready}`),
330
+ () => console.info("TN_ENVIRONMENT_BAKE:finished ready=false"),
331
+ );
332
+ const remaining = deadlineMs - (globalThis.performance?.now() ?? Date.now());
333
+ if (!Number.isFinite(remaining)) return prepared;
334
+ let timer: ReturnType<typeof setTimeout> | undefined;
335
+ try {
336
+ return await Promise.race([
337
+ prepared,
338
+ new Promise<boolean>((resolve) => {
339
+ timer = setTimeout(() => resolve(false), Math.max(0, remaining));
340
+ }),
341
+ ]);
342
+ } finally {
343
+ clearTimeout(timer);
344
+ }
300
345
  }
301
346
 
302
347
  const DEFAULT_SLICE_SIZE = 24;
@@ -621,7 +666,12 @@ function collectRenderables(root: Object3D): Object3D[] {
621
666
  const stack: Object3D[] = [root];
622
667
  while (stack.length > 0) {
623
668
  const object = stack.pop() as Object3D;
624
- if ((object as Object3D & { material?: unknown }).material !== undefined) found.push(object);
669
+ // A source the engine merged draws through its merged mesh, which is counted in its place.
670
+ if (
671
+ (object as Object3D & { material?: unknown }).material !== undefined &&
672
+ !isAutoBatchSource(object)
673
+ )
674
+ found.push(object);
625
675
  // A structural stand-in for a scene may carry no children at all; count what is there.
626
676
  const children = object.children ?? [];
627
677
  for (let index = children.length - 1; index >= 0; index -= 1) {
@@ -764,14 +814,19 @@ function nodeHasReflector(root: unknown, depth: number): boolean {
764
814
 
765
815
  function hasReflector(scene: Object3D): boolean {
766
816
  const stack: Object3D[] = [scene];
817
+ // A material is read once however many objects draw with it: on the engine, every field of its
818
+ // values is a call into the host.
819
+ const read = new Set<object>();
767
820
  while (stack.length > 0) {
768
821
  const object = stack.pop() as Object3D & { material?: unknown };
769
822
  const material = object.material;
770
823
  if (
771
824
  typeof material === "object" &&
772
825
  material !== null &&
773
- (material as { isNodeMaterial?: boolean }).isNodeMaterial === true
826
+ (material as { isNodeMaterial?: boolean }).isNodeMaterial === true &&
827
+ !read.has(material)
774
828
  ) {
829
+ read.add(material);
775
830
  for (const value of Object.values(material as Record<string, unknown>)) {
776
831
  if (nodeHasReflector(value, 0)) return true;
777
832
  }
@@ -807,14 +862,18 @@ async function renderWarmPasses(
807
862
  enabled: boolean,
808
863
  includeHidden: boolean,
809
864
  targetScene?: Object3D,
865
+ afterCoveredDraw?: () => void,
810
866
  ): Promise<IWarmPassRender | undefined> {
811
867
  const coveredWorldPass = renderer.warmUpWorldPass;
812
868
  const render =
813
869
  coveredWorldPass === undefined
814
870
  ? renderer.render === undefined
815
871
  ? undefined
816
- : () => renderer.render?.(scene, camera)
817
- : () => coveredWorldPass(scene, camera, targetScene);
872
+ : () => {
873
+ renderer.render?.(scene, camera);
874
+ afterCoveredDraw?.();
875
+ }
876
+ : () => coveredWorldPass(scene, camera, targetScene, afterCoveredDraw);
818
877
  if (render === undefined) return undefined;
819
878
  const skipped: IWarmPassRender = {
820
879
  passes: [],
@@ -864,7 +923,12 @@ async function renderWarmPasses(
864
923
  }
865
924
  // The root's own visibility is forced below whether or not hidden objects are included, so it
866
925
  // is not counted here; a hidden child or group is.
867
- if (includeHidden && object !== scene && object.visible === false) {
926
+ if (
927
+ includeHidden &&
928
+ object !== scene &&
929
+ object.visible === false &&
930
+ !isAutoBatchSource(object)
931
+ ) {
868
932
  entry.visible = false;
869
933
  object.visible = true;
870
934
  visibilityForced += 1;
@@ -962,6 +1026,7 @@ export async function warmUpScene(
962
1026
  targetScene,
963
1027
  camera,
964
1028
  environmentDeadline,
1029
+ options.afterCoveredDraw,
965
1030
  ).then((prepared) => {
966
1031
  environmentPrepared = prepared;
967
1032
  if (!prepared) {
@@ -1178,6 +1243,7 @@ export async function warmUpScene(
1178
1243
  options.renderPasses !== false,
1179
1244
  options.includeHidden === true,
1180
1245
  options.targetScene,
1246
+ options.afterCoveredDraw,
1181
1247
  );
1182
1248
  } catch (error) {
1183
1249
  passError = error;