@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
@@ -235,7 +235,8 @@ export interface IDirectionalClipmapOptions {
235
235
  readonly direction: IVector3Like;
236
236
  /** Half-width of each level's window in world units, finest first. */
237
237
  readonly clipExtents: readonly number[];
238
- readonly pagesPerAxis: number;
238
+ /** Texels per window edge: one value for every level, or one per level finest first. */
239
+ readonly pagesPerAxis: number | readonly number[];
239
240
  /**
240
241
  * Fraction of an extent inside which a point selects that level, `(0, 1]`, default 0.9. One value
241
242
  * for every level, or one per level finest first, the last entry standing in for the rest.
@@ -248,6 +249,15 @@ export interface IDirectionalClipmapOptions {
248
249
  * for every level, or one per level finest first, the last entry standing in for the rest.
249
250
  */
250
251
  readonly refreshStep?: number | readonly number[];
252
+ /**
253
+ * The smallest ratio of a window's light-space height to its width, `(0, 1]`, default 1. A low
254
+ * sun stretches a texel along the light's V axis by `1 / sin(elevation)` of floor, so a window
255
+ * the same height as it is wide would make every shadow edge across the floor that much blurrier.
256
+ * A ratio below 1 shrinks the height to `sin(elevation)`, never under this value, and the texels
257
+ * then cover the same floor area at any sun height. A sun within 18 degrees of the zenith keeps
258
+ * square windows. Page coordinates stay square: `v` counts pages in that shrunken height.
259
+ */
260
+ readonly minAspect?: number;
251
261
  }
252
262
 
253
263
  function dot(a: IVector3Like, b: IVector3Like): number {
@@ -286,7 +296,8 @@ function cornersOfBounds(bounds: IBoundsLike): IVector3Like[] {
286
296
  */
287
297
  export class DirectionalClipmap {
288
298
  readonly clipExtents: readonly number[];
289
- readonly pagesPerAxis: number;
299
+ /** Texels per window edge, one per level, finest first. */
300
+ #pages: number[] = [];
290
301
  /**
291
302
  * Per level, finest first; the last entry stands in for every level past it. Mutable through
292
303
  * {@link setRefreshStep} so a level whose own render is expensive can be stepped further, which
@@ -299,6 +310,9 @@ export class DirectionalClipmap {
299
310
  basisU: IVector3Like;
300
311
  basisV: IVector3Like;
301
312
  basisW: IVector3Like;
313
+ /** Window height over width: `v` is metres along `basisV` divided by this. 1 is a square window. */
314
+ vScale = 1;
315
+ readonly minAspect: number;
302
316
  centerWorld: IVector3Like = { x: 0, y: 0, z: 0 };
303
317
  centerLight: ILightSpacePoint = { u: 0, v: 0, w: 0 };
304
318
  #windows: IClipWindow[] = [];
@@ -314,9 +328,13 @@ export class DirectionalClipmap {
314
328
  pagesPerAxis,
315
329
  selectionGuard = 0.9,
316
330
  refreshStep = 0.125,
331
+ minAspect = 1,
317
332
  }: IDirectionalClipmapOptions) {
318
333
  assertFiniteVector("direction", direction);
319
- assertPositiveInteger("pagesPerAxis", pagesPerAxis);
334
+ if (!Number.isFinite(minAspect) || minAspect <= 0 || minAspect > 1) {
335
+ throw new RangeError(`minAspect must be in the range (0, 1], got ${String(minAspect)}`);
336
+ }
337
+ this.minAspect = minAspect;
320
338
  if (!Array.isArray(clipExtents) || clipExtents.length === 0) {
321
339
  throw new TypeError("clipExtents must be a non-empty array");
322
340
  }
@@ -364,7 +382,7 @@ export class DirectionalClipmap {
364
382
  }
365
383
  }
366
384
  this.clipExtents = [...clipExtents];
367
- this.pagesPerAxis = pagesPerAxis;
385
+ this.setPagesPerAxis(pagesPerAxis);
368
386
  this.refreshStep = clipExtents.map((_, level) => this.#perLevel(steps, level));
369
387
  this.selectionGuard = guards;
370
388
  this.levelCount = clipExtents.length;
@@ -384,6 +402,12 @@ export class DirectionalClipmap {
384
402
  Math.abs(this.basisW.y) > 0.95 ? { x: 0, y: 0, z: 1 } : { x: 0, y: 1, z: 0 };
385
403
  this.basisU = normalize(cross(this.basisW, reference));
386
404
  this.basisV = normalize(cross(this.basisW, this.basisU));
405
+ // Only a sun low enough that V is the ground's slope axis: near the zenith the basis turns to
406
+ // the +z reference and V is no longer the direction a floor texel stretches along.
407
+ this.vScale =
408
+ Math.abs(this.basisW.y) > 0.95
409
+ ? 1
410
+ : Math.min(1, Math.max(this.minAspect, Math.abs(this.basisW.y)));
387
411
  if (!unchanged) this.#windows = [];
388
412
  this.updateCenter(this.centerWorld);
389
413
  return !unchanged;
@@ -393,7 +417,7 @@ export class DirectionalClipmap {
393
417
  assertFiniteVector("worldPoint", worldPoint);
394
418
  return {
395
419
  u: dot(worldPoint, this.basisU),
396
- v: dot(worldPoint, this.basisV),
420
+ v: dot(worldPoint, this.basisV) / this.vScale,
397
421
  w: dot(worldPoint, this.basisW),
398
422
  };
399
423
  }
@@ -402,10 +426,11 @@ export class DirectionalClipmap {
402
426
  if (![u, v, w].every(Number.isFinite)) {
403
427
  throw new TypeError("light-space coordinates must be finite");
404
428
  }
429
+ const along = v * this.vScale;
405
430
  return {
406
- x: this.basisU.x * u + this.basisV.x * v + this.basisW.x * w,
407
- y: this.basisU.y * u + this.basisV.y * v + this.basisW.y * w,
408
- z: this.basisU.z * u + this.basisV.z * v + this.basisW.z * w,
431
+ x: this.basisU.x * u + this.basisV.x * along + this.basisW.x * w,
432
+ y: this.basisU.y * u + this.basisV.y * along + this.basisW.y * w,
433
+ z: this.basisU.z * u + this.basisV.z * along + this.basisW.z * w,
409
434
  };
410
435
  }
411
436
 
@@ -419,14 +444,29 @@ export class DirectionalClipmap {
419
444
  this.refreshStep[level] = step;
420
445
  }
421
446
 
447
+ /** Texels per edge of `level`'s window. */
448
+ pagesAt(level: number): number {
449
+ return this.#perLevel(this.#pages, level);
450
+ }
451
+
452
+ /** Resize the windows (one value, or one per level); every window is placed afresh. */
453
+ setPagesPerAxis(pagesPerAxis: number | readonly number[]): void {
454
+ const pages = typeof pagesPerAxis === "number" ? [pagesPerAxis] : [...pagesPerAxis];
455
+ if (pages.length === 0) throw new TypeError("pagesPerAxis must not be empty");
456
+ for (const value of pages) assertPositiveInteger("pagesPerAxis", value);
457
+ this.#pages = pages;
458
+ this.#windows = [];
459
+ }
460
+
422
461
  updateCenter(worldPoint: IVector3Like): readonly IClipWindow[] {
423
462
  assertFiniteVector("worldPoint", worldPoint);
424
463
  const previousCenter = this.centerLight;
425
464
  this.centerWorld = { x: worldPoint.x, y: worldPoint.y, z: worldPoint.z };
426
465
  this.centerLight = this.project(worldPoint);
427
- const halfPages = Math.floor(this.pagesPerAxis / 2);
428
466
  this.#windows = this.clipExtents.map((extent, level) => {
429
- const pageWorldSize = (extent * 2) / this.pagesPerAxis;
467
+ const pages = this.pagesAt(level);
468
+ const halfPages = Math.floor(pages / 2);
469
+ const pageWorldSize = (extent * 2) / pages;
430
470
  // The step is a drift threshold, never the grid spacing. Changing it alone cannot move a
431
471
  // stationary window. When either axis crosses the threshold, recenter the whole window on
432
472
  // this level's fixed texel grid; `refreshStep: 0` keeps the old one-page floor addressing.
@@ -458,8 +498,8 @@ export class DirectionalClipmap {
458
498
  refreshPages,
459
499
  minX,
460
500
  minY,
461
- maxX: minX + this.pagesPerAxis,
462
- maxY: minY + this.pagesPerAxis,
501
+ maxX: minX + pages,
502
+ maxY: minY + pages,
463
503
  };
464
504
  });
465
505
  return this.#windows;
@@ -825,3 +865,63 @@ export class ShadowInvalidationTracker {
825
865
  this.#invalidated.clear();
826
866
  }
827
867
  }
868
+
869
+ /** What {@link clipmapMapSizes} measures: the levels, and the view that reads them. */
870
+ export interface IClipmapSizeRule {
871
+ /** Half-widths, finest first, as the node holds them. */
872
+ readonly clipExtents: readonly number[];
873
+ /** The fraction of each extent a receiver leaves the level at (guard minus refresh step). */
874
+ readonly selectionGuard: readonly number[];
875
+ /** `r.Shadow.Virtual.ResolutionLodBiasDirectional`: -1 halves every texel. */
876
+ readonly resolutionLodBias: number;
877
+ /** `tan(horizontal fov / 2)` of the camera that reads the shadow. */
878
+ readonly tanHalfFov: number;
879
+ /** The camera's viewport width in pixels. */
880
+ readonly viewportWidth: number;
881
+ /** Sizes are whole multiples of this. Default 128, the native page. */
882
+ readonly pageTexels?: number;
883
+ /** The most pages of `pageTexels²` all levels may hold. Default 4096. */
884
+ readonly maxPhysicalPages?: number;
885
+ /** The largest size of one level. Default 4096. */
886
+ readonly maxMapSize?: number;
887
+ }
888
+
889
+ /**
890
+ * Texels per edge of each clip level, from Unreal's clipmap rule. A receiver at distance `d` reads level
891
+ * `floor(log2(d) + bias + log2(LodScale))` with `LodScale = 0.5 tan(hfov / 2) 16384 / width` (UE 5.8.3:
892
+ * Engine/Source/Runtime/Renderer/Private/VirtualShadowMaps/VirtualShadowMapClipmap.cpp:245-254,
893
+ * Engine/Shaders/Private/VirtualShadowMaps/VirtualShadowMapPageMarking.ush:35-39), and that level is
894
+ * 16384 texels across twice its radius on each side (`HalfLevelDim`, VirtualShadowMapClipmap.cpp:363,
895
+ * :452), so a texel is `2^bias` to `2^(1 + bias)` of the receiver's own screen pixels. A level here
896
+ * gets that worst case at the nearest receiver it serves: the guarded edge of the level inside it (the
897
+ * finest, one level step nearer still). When the sizes outgrow the page budget, the bias rises a
898
+ * quarter stop at a time until they fit, as Unreal raises its global bias when the page pool is over
899
+ * budget (VirtualShadowMapCacheManager.cpp:703-717).
900
+ */
901
+ export function clipmapMapSizes(rule: IClipmapSizeRule): number[] {
902
+ const { clipExtents, selectionGuard, tanHalfFov, viewportWidth } = rule;
903
+ const page = rule.pageTexels ?? 128;
904
+ const maxPages = rule.maxPhysicalPages ?? 4096;
905
+ const maxSize = rule.maxMapSize ?? 4096;
906
+ if (!(tanHalfFov > 0) || !(viewportWidth > 0) || !Number.isFinite(rule.resolutionLodBias))
907
+ throw new RangeError(
908
+ "clipmapMapSizes needs a positive tanHalfFov and viewportWidth and a finite bias",
909
+ );
910
+ const guard = (level: number): number =>
911
+ selectionGuard[Math.min(level, selectionGuard.length - 1)] as number;
912
+ const first = clipExtents[0] as number;
913
+ const inner = clipExtents.map((extent, level) =>
914
+ level === 0
915
+ ? guard(0) * first * (clipExtents.length > 1 ? first / (clipExtents[1] as number) : 0.5)
916
+ : guard(level - 1) * (clipExtents[level - 1] as number),
917
+ );
918
+ for (let bias = rule.resolutionLodBias; ; bias += 0.25) {
919
+ const sizes = clipExtents.map((extent, level) => {
920
+ const pixel = (2 * (inner[level] as number) * tanHalfFov) / viewportWidth;
921
+ const texels = Math.ceil((2 * extent) / (2 ** (1 + bias) * pixel) / page) * page;
922
+ return Math.min(maxSize, Math.max(page, texels));
923
+ });
924
+ const pages = sizes.reduce((sum, size) => sum + (size / page) ** 2, 0);
925
+ if (pages <= maxPages || sizes.every((size) => size === page)) return sizes;
926
+ }
927
+ }