@threenative/core 0.3.15 → 0.3.17

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.
@@ -1080,7 +1080,7 @@ index 7c8d2322834904c1247c79cda31beff8e2bfc497..b87cf38629b2c52804888a10bda3b814
1080
1080
 
1081
1081
  }
1082
1082
  diff --git a/build/three.webgpu.js b/build/three.webgpu.js
1083
- index f8fc49fe7df98cbac4609603a1f2a2c6aea79675..a458a6d75ee95fdb9913222f4ed31c5c3cc56b09 100644
1083
+ index f8fc49fe7df98cbac4609603a1f2a2c6aea79675..e6d9e39318189f6e555be86f2a57d9467fc1188d 100644
1084
1084
  --- a/build/three.webgpu.js
1085
1085
  +++ b/build/three.webgpu.js
1086
1086
  @@ -5182,7 +5182,7 @@ class Animation {
@@ -2992,7 +2992,36 @@ index f8fc49fe7df98cbac4609603a1f2a2c6aea79675..a458a6d75ee95fdb9913222f4ed31c5c
2992
2992
 
2993
2993
  }
2994
2994
 
2995
- @@ -51001,6 +51777,7 @@ class WebGPUBackend extends Backend {
2995
+ @@ -49324,28 +50100,24 @@
2996
+ _viewDescriptor.dimension = GPUTextureViewDimension.TwoD;
2997
+
2998
+ const textureView = textureData.texture.createView( _viewDescriptor );
2999
+ const msaaTexture = textureData.msaaTextures?.[ layer ];
3000
+ textureViews.push( {
3001
+ view: msaaTexture !== undefined ? msaaTexture.createView() : textureView,
3002
+ resolveTarget: msaaTexture !== undefined && renderTarget.resolveColorBuffer === true ? textureView : undefined,
3003
+ depthSlice: undefined
3004
+ } );
3005
+
3006
+ }
3007
+
3008
+ - } else {
3009
+ -
3010
+ - _viewDescriptor.dimension = GPUTextureViewDimension.TwoDArray;
3011
+ -
3012
+ }
3013
+
3014
+ }
3015
+
3016
+ if ( isRenderCameraDepthArray !== true ) {
3017
+
3018
+ const textureView = textureData.texture.createView( _viewDescriptor );
3019
+
3020
+ let view, resolveTarget;
3021
+
3022
+ if ( textureData.msaaTexture !== undefined ) {
3023
+
3024
+ @@ -51001,6 +51773,7 @@ class WebGPUBackend extends Backend {
2996
3025
  const utils = this.utils;
2997
3026
 
2998
3027
  const sampleCount = utils.getSampleCountRenderContext( renderObject.context );
@@ -3000,7 +3029,7 @@ index f8fc49fe7df98cbac4609603a1f2a2c6aea79675..a458a6d75ee95fdb9913222f4ed31c5c
3000
3029
  const colorSpace = utils.getCurrentColorSpace( renderObject.context );
3001
3030
  const colorFormat = utils.getCurrentColorFormat( renderObject.context );
3002
3031
  const depthStencilFormat = utils.getCurrentDepthStencilFormat( renderObject.context );
3003
- @@ -51025,7 +51802,8 @@ class WebGPUBackend extends Backend {
3032
+ @@ -51025,7 +51798,8 @@ class WebGPUBackend extends Backend {
3004
3033
  data.primitiveTopology !== primitiveTopology || data.stripIndexFormat !== stripIndexFormat ||
3005
3034
  data.frontFaceCW !== frontFaceCW ||
3006
3035
  data.geometryVersion !== renderObject.geometryVersion ||
@@ -3010,7 +3039,7 @@ index f8fc49fe7df98cbac4609603a1f2a2c6aea79675..a458a6d75ee95fdb9913222f4ed31c5c
3010
3039
  ) {
3011
3040
 
3012
3041
  data.material = material; data.materialVersion = material.version;
3013
- @@ -51048,6 +51826,7 @@ class WebGPUBackend extends Backend {
3042
+ @@ -51048,6 +51822,7 @@ class WebGPUBackend extends Backend {
3014
3043
  data.frontFaceCW = frontFaceCW;
3015
3044
  data.geometryVersion = renderObject.geometryVersion;
3016
3045
  data.clippingContextCacheKey = renderObject.clippingContextCacheKey;
@@ -3018,7 +3047,7 @@ index f8fc49fe7df98cbac4609603a1f2a2c6aea79675..a458a6d75ee95fdb9913222f4ed31c5c
3018
3047
 
3019
3048
  needsUpdate = true;
3020
3049
 
3021
- @@ -51069,6 +51848,7 @@ class WebGPUBackend extends Backend {
3050
+ @@ -51069,6 +51844,7 @@ class WebGPUBackend extends Backend {
3022
3051
 
3023
3052
  const utils = this.utils;
3024
3053
  const renderContext = renderObject.context;
@@ -3026,7 +3055,7 @@ index f8fc49fe7df98cbac4609603a1f2a2c6aea79675..a458a6d75ee95fdb9913222f4ed31c5c
3026
3055
 
3027
3056
  // meshes with negative scale have a different frontFace render pipeline
3028
3057
  // descriptor value so the following must be honored in the cache key
3029
- @@ -51088,9 +51868,11 @@ class WebGPUBackend extends Backend {
3058
+ @@ -51088,9 +51864,11 @@ class WebGPUBackend extends Backend {
3030
3059
  material.side, material.alphaToCoverage,
3031
3060
  frontFaceCW,
3032
3061
  utils.getSampleCountRenderContext( renderContext ),
@@ -3038,7 +3067,7 @@ index f8fc49fe7df98cbac4609603a1f2a2c6aea79675..a458a6d75ee95fdb9913222f4ed31c5c
3038
3067
  renderObject.clippingContextCacheKey
3039
3068
  ].join();
3040
3069
 
3041
- @@ -51158,6 +51940,12 @@ class WebGPUBackend extends Backend {
3070
+ @@ -51158,6 +51936,12 @@ class WebGPUBackend extends Backend {
3042
3071
 
3043
3072
  }
3044
3073
 
@@ -3052,7 +3081,7 @@ index f8fc49fe7df98cbac4609603a1f2a2c6aea79675..a458a6d75ee95fdb9913222f4ed31c5c
3052
3081
  * Generates mipmaps for the given texture.
3053
3082
  *
3054
3083
  diff --git a/build/three.webgpu.nodes.js b/build/three.webgpu.nodes.js
3055
- index 39c897cb2f5f2092419c2cd4f464a88f1151d7d0..790d97c1247564c7fd3aea2ee54ea0a6ffa50c62 100644
3084
+ index 39c897cb2f5f2092419c2cd4f464a88f1151d7d0..40a12e5262477dca5218c1e3396d07223adb673a 100644
3056
3085
  --- a/build/three.webgpu.nodes.js
3057
3086
  +++ b/build/three.webgpu.nodes.js
3058
3087
  @@ -179,6 +179,15 @@ class NodeMaterialObserver {
@@ -6034,7 +6063,36 @@ index 39c897cb2f5f2092419c2cd4f464a88f1151d7d0..790d97c1247564c7fd3aea2ee54ea0a6
6034
6063
 
6035
6064
  }
6036
6065
 
6037
- @@ -92203,6 +93639,7 @@ class WebGPUBackend extends Backend {
6066
+ @@ -90525,28 +91961,24 @@
6067
+ _viewDescriptor.arrayLayerCount = 1;
6068
+ _viewDescriptor.dimension = GPUTextureViewDimension.TwoD;
6069
+
6070
+ const textureView = textureData.texture.createView( _viewDescriptor );
6071
+ const msaaTexture = textureData.msaaTextures?.[ layer ];
6072
+ textureViews.push( {
6073
+ view: msaaTexture !== undefined ? msaaTexture.createView() : textureView,
6074
+ resolveTarget: msaaTexture !== undefined && renderTarget.resolveColorBuffer === true ? textureView : undefined,
6075
+ depthSlice: undefined
6076
+ } );
6077
+
6078
+ }
6079
+ -
6080
+ - } else {
6081
+ -
6082
+ - _viewDescriptor.dimension = GPUTextureViewDimension.TwoDArray;
6083
+
6084
+ }
6085
+
6086
+ }
6087
+
6088
+ if ( isRenderCameraDepthArray !== true ) {
6089
+
6090
+ const textureView = textureData.texture.createView( _viewDescriptor );
6091
+
6092
+ let view, resolveTarget;
6093
+
6094
+ if ( textureData.msaaTexture !== undefined ) {
6095
+ @@ -92203,6 +93635,7 @@ class WebGPUBackend extends Backend {
6038
6096
  const utils = this.utils;
6039
6097
 
6040
6098
  const sampleCount = utils.getSampleCountRenderContext( renderObject.context );
@@ -6042,7 +6100,7 @@ index 39c897cb2f5f2092419c2cd4f464a88f1151d7d0..790d97c1247564c7fd3aea2ee54ea0a6
6042
6100
  const colorSpace = utils.getCurrentColorSpace( renderObject.context );
6043
6101
  const colorFormat = utils.getCurrentColorFormat( renderObject.context );
6044
6102
  const depthStencilFormat = utils.getCurrentDepthStencilFormat( renderObject.context );
6045
- @@ -92227,7 +93664,8 @@ class WebGPUBackend extends Backend {
6103
+ @@ -92227,7 +93660,8 @@ class WebGPUBackend extends Backend {
6046
6104
  data.primitiveTopology !== primitiveTopology || data.stripIndexFormat !== stripIndexFormat ||
6047
6105
  data.frontFaceCW !== frontFaceCW ||
6048
6106
  data.geometryVersion !== renderObject.geometryVersion ||
@@ -6052,7 +6110,7 @@ index 39c897cb2f5f2092419c2cd4f464a88f1151d7d0..790d97c1247564c7fd3aea2ee54ea0a6
6052
6110
  ) {
6053
6111
 
6054
6112
  data.material = material; data.materialVersion = material.version;
6055
- @@ -92250,6 +93688,7 @@ class WebGPUBackend extends Backend {
6113
+ @@ -92250,6 +93684,7 @@ class WebGPUBackend extends Backend {
6056
6114
  data.frontFaceCW = frontFaceCW;
6057
6115
  data.geometryVersion = renderObject.geometryVersion;
6058
6116
  data.clippingContextCacheKey = renderObject.clippingContextCacheKey;
@@ -6060,7 +6118,7 @@ index 39c897cb2f5f2092419c2cd4f464a88f1151d7d0..790d97c1247564c7fd3aea2ee54ea0a6
6060
6118
 
6061
6119
  needsUpdate = true;
6062
6120
 
6063
- @@ -92271,6 +93710,7 @@ class WebGPUBackend extends Backend {
6121
+ @@ -92271,6 +93706,7 @@ class WebGPUBackend extends Backend {
6064
6122
 
6065
6123
  const utils = this.utils;
6066
6124
  const renderContext = renderObject.context;
@@ -6068,7 +6126,7 @@ index 39c897cb2f5f2092419c2cd4f464a88f1151d7d0..790d97c1247564c7fd3aea2ee54ea0a6
6068
6126
 
6069
6127
  // meshes with negative scale have a different frontFace render pipeline
6070
6128
  // descriptor value so the following must be honored in the cache key
6071
- @@ -92290,9 +93730,11 @@ class WebGPUBackend extends Backend {
6129
+ @@ -92290,9 +93726,11 @@ class WebGPUBackend extends Backend {
6072
6130
  material.side, material.alphaToCoverage,
6073
6131
  frontFaceCW,
6074
6132
  utils.getSampleCountRenderContext( renderContext ),
@@ -6080,7 +6138,7 @@ index 39c897cb2f5f2092419c2cd4f464a88f1151d7d0..790d97c1247564c7fd3aea2ee54ea0a6
6080
6138
  renderObject.clippingContextCacheKey
6081
6139
  ].join();
6082
6140
 
6083
- @@ -92360,6 +93802,12 @@ class WebGPUBackend extends Backend {
6141
+ @@ -92360,6 +93798,12 @@ class WebGPUBackend extends Backend {
6084
6142
 
6085
6143
  }
6086
6144
 
@@ -8357,7 +8415,7 @@ index 6f6a362a36b34c0b6cf7e3c93e818586822c6f3e..46f351dc993df997be456adc176b4a1e
8357
8415
 
8358
8416
  }
8359
8417
  diff --git a/src/renderers/webgpu/WebGPUBackend.js b/src/renderers/webgpu/WebGPUBackend.js
8360
- index 719d67abe3986ca058794b63a441ce66bedde891..39001c639aafb8422852c8b75ce1ee357427b174 100644
8418
+ index 719d67abe3986ca058794b63a441ce66bedde891..9eee576d31cc5329ed67eb8e0ccba6f96edca088 100644
8361
8419
  --- a/src/renderers/webgpu/WebGPUBackend.js
8362
8420
  +++ b/src/renderers/webgpu/WebGPUBackend.js
8363
8421
  @@ -106,6 +106,27 @@ class WebGPUBackend extends Backend {
@@ -8422,7 +8480,36 @@ index 719d67abe3986ca058794b63a441ce66bedde891..39001c639aafb8422852c8b75ce1ee35
8422
8480
 
8423
8481
  }
8424
8482
 
8425
- @@ -2414,6 +2444,7 @@ class WebGPUBackend extends Backend {
8483
+ @@ -736,28 +766,24 @@
8484
+ _viewDescriptor.arrayLayerCount = 1;
8485
+ _viewDescriptor.dimension = GPUTextureViewDimension.TwoD;
8486
+
8487
+ const textureView = textureData.texture.createView( _viewDescriptor );
8488
+ const msaaTexture = textureData.msaaTextures?.[ layer ];
8489
+ textureViews.push( {
8490
+ view: msaaTexture !== undefined ? msaaTexture.createView() : textureView,
8491
+ resolveTarget: msaaTexture !== undefined && renderTarget.resolveColorBuffer === true ? textureView : undefined,
8492
+ depthSlice: undefined
8493
+ } );
8494
+
8495
+ }
8496
+ -
8497
+ - } else {
8498
+ -
8499
+ - _viewDescriptor.dimension = GPUTextureViewDimension.TwoDArray;
8500
+
8501
+ }
8502
+
8503
+ }
8504
+
8505
+ if ( isRenderCameraDepthArray !== true ) {
8506
+
8507
+ const textureView = textureData.texture.createView( _viewDescriptor );
8508
+
8509
+ let view, resolveTarget;
8510
+
8511
+ if ( textureData.msaaTexture !== undefined ) {
8512
+ @@ -2414,6 +2440,7 @@ class WebGPUBackend extends Backend {
8426
8513
  const utils = this.utils;
8427
8514
 
8428
8515
  const sampleCount = utils.getSampleCountRenderContext( renderObject.context );
@@ -8430,7 +8517,7 @@ index 719d67abe3986ca058794b63a441ce66bedde891..39001c639aafb8422852c8b75ce1ee35
8430
8517
  const colorSpace = utils.getCurrentColorSpace( renderObject.context );
8431
8518
  const colorFormat = utils.getCurrentColorFormat( renderObject.context );
8432
8519
  const depthStencilFormat = utils.getCurrentDepthStencilFormat( renderObject.context );
8433
- @@ -2438,7 +2469,8 @@ class WebGPUBackend extends Backend {
8520
+ @@ -2438,7 +2465,8 @@ class WebGPUBackend extends Backend {
8434
8521
  data.primitiveTopology !== primitiveTopology || data.stripIndexFormat !== stripIndexFormat ||
8435
8522
  data.frontFaceCW !== frontFaceCW ||
8436
8523
  data.geometryVersion !== renderObject.geometryVersion ||
@@ -8440,7 +8527,7 @@ index 719d67abe3986ca058794b63a441ce66bedde891..39001c639aafb8422852c8b75ce1ee35
8440
8527
  ) {
8441
8528
 
8442
8529
  data.material = material; data.materialVersion = material.version;
8443
- @@ -2461,6 +2493,7 @@ class WebGPUBackend extends Backend {
8530
+ @@ -2461,6 +2489,7 @@ class WebGPUBackend extends Backend {
8444
8531
  data.frontFaceCW = frontFaceCW;
8445
8532
  data.geometryVersion = renderObject.geometryVersion;
8446
8533
  data.clippingContextCacheKey = renderObject.clippingContextCacheKey;
@@ -8448,7 +8535,7 @@ index 719d67abe3986ca058794b63a441ce66bedde891..39001c639aafb8422852c8b75ce1ee35
8448
8535
 
8449
8536
  needsUpdate = true;
8450
8537
 
8451
- @@ -2482,6 +2515,7 @@ class WebGPUBackend extends Backend {
8538
+ @@ -2482,6 +2511,7 @@ class WebGPUBackend extends Backend {
8452
8539
 
8453
8540
  const utils = this.utils;
8454
8541
  const renderContext = renderObject.context;
@@ -8456,7 +8543,7 @@ index 719d67abe3986ca058794b63a441ce66bedde891..39001c639aafb8422852c8b75ce1ee35
8456
8543
 
8457
8544
  // meshes with negative scale have a different frontFace render pipeline
8458
8545
  // descriptor value so the following must be honored in the cache key
8459
- @@ -2501,9 +2535,11 @@ class WebGPUBackend extends Backend {
8546
+ @@ -2501,9 +2531,11 @@ class WebGPUBackend extends Backend {
8460
8547
  material.side, material.alphaToCoverage,
8461
8548
  frontFaceCW,
8462
8549
  utils.getSampleCountRenderContext( renderContext ),
@@ -8468,7 +8555,7 @@ index 719d67abe3986ca058794b63a441ce66bedde891..39001c639aafb8422852c8b75ce1ee35
8468
8555
  renderObject.clippingContextCacheKey
8469
8556
  ].join();
8470
8557
 
8471
- @@ -2571,6 +2607,12 @@ class WebGPUBackend extends Backend {
8558
+ @@ -2571,6 +2603,12 @@ class WebGPUBackend extends Backend {
8472
8559
 
8473
8560
  }
8474
8561
 
@@ -35,3 +35,32 @@ export function copyMatrixWorld(object: Object3D, target: Matrix4): boolean {
35
35
  hook.call(object, target);
36
36
  return true;
37
37
  }
38
+
39
+ /**
40
+ * PRD-898 J4: the owned engine's posed-bounds call. `root.__tnSphereBounds(objects, radii)` runs
41
+ * `root.updateWorldMatrix(true, true)` and answers `[minX, minY, minZ, maxX, maxY, maxZ]` over a sphere
42
+ * of `radii[i]` at each object's world origin, in one crossing instead of one per bone. The engine
43
+ * defines it in `runtime-native/src/engine/abi/bindings_scene.cpp`; plain three.js has none.
44
+ */
45
+ export const SPHERE_BOUNDS_HOOK = "__tnSphereBounds";
46
+
47
+ /** The spheres are handed to the engine once; the per-frame call then takes no arguments. */
48
+ export const SPHERE_BOUNDS_ATTACH_HOOK = "__tnSphereBoundsAttach";
49
+
50
+ interface ISphereBoundsHooks {
51
+ readonly attach: (objects: readonly Object3D[], radii: readonly number[]) => void;
52
+ readonly bounds: () => readonly number[];
53
+ }
54
+
55
+ /** The engine's sphere-bounds calls on `root`, or undefined on plain three.js. */
56
+ export function sphereBoundsHook(root: Object3D): ISphereBoundsHooks | undefined {
57
+ const carrier = root as Object3D & Record<string, unknown>;
58
+ const attach = carrier[SPHERE_BOUNDS_ATTACH_HOOK];
59
+ const bounds = carrier[SPHERE_BOUNDS_HOOK];
60
+ return typeof attach === "function" && typeof bounds === "function"
61
+ ? {
62
+ attach: attach as ISphereBoundsHooks["attach"],
63
+ bounds: bounds as ISphereBoundsHooks["bounds"],
64
+ }
65
+ : undefined;
66
+ }
package/src/grounding.ts CHANGED
@@ -47,23 +47,25 @@ export class GroundSnap {
47
47
  throw new Error("GroundSnap dt must be finite and non-negative.");
48
48
  validateMaxRate(this.maxRate);
49
49
 
50
- const before = posedBounds(this.model, this.meshes);
51
- if (!Number.isFinite(before.min[1])) {
50
+ const lowest = posedBounds(this.model, this.meshes).min[1];
51
+ if (!Number.isFinite(lowest)) {
52
52
  this.clearance = null;
53
53
  return;
54
54
  }
55
55
 
56
- const desired = surfaceY - before.min[1];
56
+ const desired = surfaceY - lowest;
57
57
  const correction =
58
58
  this.maxRate === undefined || desired > 0 ? desired : Math.max(desired, -this.maxRate * dt);
59
- if (this.enabled) this.applyWorldCorrection(group, correction);
59
+ const moved = this.enabled && correction !== 0;
60
+ if (moved) this.applyWorldCorrection(group, correction);
60
61
 
61
- // Re-read after the move. The group may be under a scaled or rotated parent, so the local
62
- // correction is not always one world metre for one local metre. posedBounds forces its own
63
- // whole-subtree matrix pass, so no explicit update here — that was a second full pass per
64
- // grounded character per frame buying nothing the measurement below does not redo.
65
- const after = posedBounds(this.model, this.meshes);
66
- this.clearance = after.min[1] - surfaceY;
62
+ // PRD-898 J4: the correction is a world-space translation of `group`, so when `group` carries the
63
+ // model the lowest point moved by exactly `correction` and a second measurement (a whole-subtree
64
+ // matrix pass per grounded character per frame) would only re-read it. A `group` that does not
65
+ // carry the model is measured again, as before.
66
+ if (!moved) this.clearance = lowest - surfaceY;
67
+ else if (carries(group, this.model)) this.clearance = lowest + correction - surfaceY;
68
+ else this.clearance = posedBounds(this.model, this.meshes).min[1] - surfaceY;
67
69
  }
68
70
 
69
71
  private applyWorldCorrection(group: Object3D, correction: number): void {
@@ -94,6 +96,13 @@ export class GroundSnap {
94
96
  }
95
97
  }
96
98
 
99
+ /** Whether `group` is `model` or one of its ancestors, so moving it moves the model. */
100
+ function carries(group: Object3D, model: Object3D): boolean {
101
+ for (let node: Object3D | null = model; node !== null; node = node.parent)
102
+ if (node === group) return true;
103
+ return false;
104
+ }
105
+
97
106
  function validateMaxRate(maxRate: number | undefined): void {
98
107
  if (maxRate !== undefined && (!Number.isFinite(maxRate) || maxRate < 0)) {
99
108
  throw new Error("GroundSnap maxRate must be finite and non-negative.");
package/src/hot.ts CHANGED
@@ -131,6 +131,23 @@ function diagnostics<TState extends Record<string, unknown>, TPhysics>(
131
131
  physics: typeof physics?.numBodies === "function" ? physics.numBodies() : null,
132
132
  };
133
133
  }
134
+ /**
135
+ * Name the class and the shape to store: an agent told only "plain objects" rewrites the wrong thing
136
+ * (hosted Studio, 2026-11-17: a Vector3 in state reloaded the page on every edit).
137
+ */
138
+ function notPlain(value: object, prototype: object, path: string): Error {
139
+ const named = (prototype as { constructor?: { name?: unknown } }).constructor?.name;
140
+ const name = typeof named === "string" && named.length > 0 ? named : "class instance";
141
+ // three keeps some fields private (`Quaternion._x`): the shape to store is the public name.
142
+ const keys = Object.keys(value).map((key) => key.replace(/^_/u, ""));
143
+ const shape =
144
+ keys.length > 0 && keys.length <= 6
145
+ ? `{ ${keys.join(", ")} } as a plain object`
146
+ : "its data as plain values";
147
+ return new Error(
148
+ `Hot reload state ${path} must contain only plain objects: it is a ${name}. Store ${shape} and rebuild the ${name} where the code needs it.`,
149
+ );
150
+ }
134
151
  function visitPortable(value: unknown, path: string, ancestors: Set<object>): void {
135
152
  if (value === null) return;
136
153
  if (typeof value === "string" || typeof value === "boolean") return;
@@ -149,8 +166,7 @@ function visitPortable(value: unknown, path: string, ancestors: Set<object>): vo
149
166
  return;
150
167
  }
151
168
  const prototype = Object.getPrototypeOf(value);
152
- if (prototype !== Object.prototype && prototype !== null)
153
- throw new Error(`Hot reload state ${path} must contain only plain objects.`);
169
+ if (prototype !== Object.prototype && prototype !== null) throw notPlain(value, prototype, path);
154
170
  ancestors.add(value);
155
171
  for (const key of Object.keys(value))
156
172
  visitPortable((value as Record<string, unknown>)[key], `${path}.${key}`, ancestors);
package/src/index.ts CHANGED
@@ -1574,7 +1574,7 @@ export type {
1574
1574
  * @constraint call `update(follow)` once per rendered frame
1575
1575
  * @constraint `place` runs once per candidate per tile build: return false for paths and clearings
1576
1576
  * @constraint rotating or scaling the field is not supported; translating it is
1577
- * @requires npm i -D @threenative/procedural-vegetation for the bake these instances come from
1577
+ * @requires npm i -D @threenative/procedural-environment for the bake these instances come from
1578
1578
  * @example
1579
1579
  * const floor = new ScatterField3D({ parts: [{ lods, material }], getHeight, density: 0.05, place });
1580
1580
  * ctx.add(floor);
@@ -11,6 +11,7 @@ import {
11
11
  DISCRETE_LOD_DEFAULT_HYSTERESIS,
12
12
  type IModelLodController,
13
13
  biasedLodDistance,
14
+ lodBias,
14
15
  lodChainOf,
15
16
  registerModelLodController,
16
17
  selectLodFor,
@@ -155,6 +156,24 @@ export function attachInstancedLod(mesh: InstancedMesh, options: IInstancedLodOp
155
156
  const sphere = new Sphere();
156
157
  let children: InstancedMesh[] = [];
157
158
  let triangles = 0;
159
+ // PRD-898 J3: on the owned engine the per-instance sort below is one call a frame
160
+ // (`lod::selectInstancedLods`), handed the partitions once, instead of three crossings per instance.
161
+ const engine = instancedLodHooks(mesh);
162
+ let attached = false;
163
+ function attachEngine(hooks: IInstancedLodHooks): void {
164
+ const authored = options.lods !== undefined;
165
+ hooks.attach.call(
166
+ mesh,
167
+ children,
168
+ Array.from(partitionOf),
169
+ authored ? distances : [],
170
+ [local.center.x, local.center.y, local.center.z, local.radius],
171
+ authored ? null : [...(chain?.errors ?? [])],
172
+ budget,
173
+ hysteresis,
174
+ );
175
+ attached = true;
176
+ }
158
177
  function ensureChildren(): void {
159
178
  if (children.length > 0) return;
160
179
  children = groups.flatMap((indices, partition) =>
@@ -186,6 +205,11 @@ export function attachInstancedLod(mesh: InstancedMesh, options: IInstancedLodOp
186
205
  },
187
206
  update(camera: Camera, viewportHeight: number): void {
188
207
  ensureChildren();
208
+ if (engine !== undefined) {
209
+ if (!attached) attachEngine(engine);
210
+ triangles = engine.update.call(mesh, camera, viewportHeight, lodBias());
211
+ return;
212
+ }
189
213
  triangles = 0;
190
214
  mesh.updateWorldMatrix(true, false);
191
215
  camera.getWorldPosition(cameraPosition);
@@ -258,6 +282,7 @@ export function attachInstancedLod(mesh: InstancedMesh, options: IInstancedLodOp
258
282
  child.dispose();
259
283
  }
260
284
  children = [];
285
+ attached = false;
261
286
  mesh.geometry = base;
262
287
  triangles = 0;
263
288
  },
@@ -276,3 +301,32 @@ export function attachInstancedLod(mesh: InstancedMesh, options: IInstancedLodOp
276
301
  ensureChildren();
277
302
  mesh.addEventListener("dispose", () => controller.release());
278
303
  }
304
+
305
+ interface IInstancedLodHooks {
306
+ readonly attach: (
307
+ children: readonly InstancedMesh[],
308
+ partitionOf: readonly number[],
309
+ distances: readonly number[],
310
+ local: readonly number[],
311
+ chainErrors: readonly number[] | null,
312
+ budget: number,
313
+ hysteresis: number,
314
+ ) => void;
315
+ readonly update: (camera: Camera, viewportHeight: number, bias: number) => number;
316
+ }
317
+
318
+ /** The owned engine's instanced LOD calls (abi/bindings_scene.cpp), or undefined on plain three.js. */
319
+ function instancedLodHooks(mesh: InstancedMesh): IInstancedLodHooks | undefined {
320
+ const carrier = mesh as InstancedMesh & {
321
+ readonly __tnInstancedLodAttach?: unknown;
322
+ readonly __tnInstancedLodUpdate?: unknown;
323
+ };
324
+ const attach = carrier.__tnInstancedLodAttach;
325
+ const update = carrier.__tnInstancedLodUpdate;
326
+ return typeof attach === "function" && typeof update === "function"
327
+ ? {
328
+ attach: attach as IInstancedLodHooks["attach"],
329
+ update: update as IInstancedLodHooks["update"],
330
+ }
331
+ : undefined;
332
+ }
package/src/model-lod.ts CHANGED
@@ -404,6 +404,35 @@ class ModelLod {
404
404
  return this.#chain.base;
405
405
  }
406
406
 
407
+ /** PRD-898 J2: whether the engine's batched selection can run this one (the join authority cannot). */
408
+ get batchable(): boolean {
409
+ return this.#rung === undefined || !this.#authority;
410
+ }
411
+
412
+ #attached = false;
413
+
414
+ /** The mesh for `__tnModelLodSelect`, its chain handed to the engine on first use. */
415
+ engineMesh(): Mesh {
416
+ if (!this.#attached) {
417
+ const { center, radius } = this.#chain.sphere;
418
+ (this.#mesh as Mesh & IModelLodEngineMesh).__tnModelLodAttach(
419
+ [...this.#chain.errors],
420
+ [center.x, center.y, center.z, radius],
421
+ this.#policy.maxPixelError,
422
+ this.#policy.hysteresis,
423
+ this.#current,
424
+ );
425
+ this.#attached = true;
426
+ }
427
+ return this.#mesh;
428
+ }
429
+
430
+ /** The level the engine's batched selection chose. */
431
+ applyLevel(index: number): void {
432
+ this.#current = index;
433
+ this.#mesh.geometry = this.#chain.levels[index] as BufferGeometry;
434
+ }
435
+
407
436
  get triangles(): number {
408
437
  // With a joined rung active, the authored primitives draw nothing and the proxy draws the
409
438
  // collapse: the authority reports the rung's triangles, every hidden sibling reports zero.
@@ -501,6 +530,23 @@ class ModelLod {
501
530
  }
502
531
  }
503
532
 
533
+ /** The owned engine's ModelLod calls (abi/bindings_scene.cpp), absent on plain three.js. */
534
+ interface IModelLodEngineMesh {
535
+ __tnModelLodAttach(
536
+ errors: readonly number[],
537
+ local: readonly number[],
538
+ maxPixelError: number,
539
+ hysteresis: number,
540
+ current: number,
541
+ ): void;
542
+ }
543
+
544
+ type ModelLodSelect = (viewportHeight: number, bias: number) => readonly number[];
545
+
546
+ interface IModelLodEngineSet {
547
+ __tnModelLodMeshes(meshes: readonly Mesh[]): void;
548
+ }
549
+
504
550
  /** Resolved runtime policy the loader stamps onto a controller, from the manifest. */
505
551
  export interface IModelLodPolicy {
506
552
  readonly hysteresis: number;
@@ -1416,6 +1462,29 @@ function trackRoot(root: IGraphNode): ITrackedRoot {
1416
1462
  *
1417
1463
  * @returns triangles the managed meshes will submit this frame.
1418
1464
  */
1465
+ /** The batched set the engine holds (`__tnModelLodMeshes`), resent only when it changes. */
1466
+ let engineBatch: readonly ModelLod[] = [];
1467
+
1468
+ /** One engine call selects every batched ModelLod; only the changed levels come back. */
1469
+ function selectBatched(
1470
+ select: ModelLodSelect,
1471
+ camera: Camera,
1472
+ batched: readonly ModelLod[],
1473
+ viewportHeight: number,
1474
+ ): void {
1475
+ if (
1476
+ batched.length !== engineBatch.length ||
1477
+ batched.some((entry, i) => entry !== engineBatch[i])
1478
+ ) {
1479
+ const meshes = batched.map((entry) => entry.engineMesh());
1480
+ (camera as Camera & IModelLodEngineSet).__tnModelLodMeshes(meshes);
1481
+ engineBatch = batched;
1482
+ }
1483
+ const changed = select.call(camera, viewportHeight, lodBias());
1484
+ for (let i = 0; i < changed.length; i += 2)
1485
+ (batched[changed[i] as number] as ModelLod).applyLevel(changed[i + 1] as number);
1486
+ }
1487
+
1419
1488
  export function updateModelLods(
1420
1489
  root: { traverse(callback: (object: object) => void): void },
1421
1490
  camera: Camera,
@@ -1436,6 +1505,10 @@ export function updateModelLods(
1436
1505
  return triangles;
1437
1506
  }
1438
1507
  const tracking = trackRoot(root);
1508
+ // PRD-898 J2: on the owned engine every plain selection is one call, and only changed levels return.
1509
+ const hook = (camera as Camera & { __tnModelLodSelect?: unknown }).__tnModelLodSelect;
1510
+ const select = typeof hook === "function" ? (hook as ModelLodSelect) : undefined;
1511
+ const batched: ModelLod[] = [];
1439
1512
  for (const mesh of tracking.items) {
1440
1513
  const entry = controllerFor(mesh);
1441
1514
  if (entry === undefined) {
@@ -1443,8 +1516,11 @@ export function updateModelLods(
1443
1516
  if (!streaming.has(mesh.geometry)) tracking.items.delete(mesh);
1444
1517
  continue;
1445
1518
  }
1446
- entry.update(camera, viewportHeight);
1519
+ if (select !== undefined && entry instanceof ModelLod && entry.batchable) batched.push(entry);
1520
+ else entry.update(camera, viewportHeight);
1447
1521
  }
1522
+ if (select !== undefined && batched.length > 0)
1523
+ selectBatched(select, camera, batched, viewportHeight);
1448
1524
  let triangles = 0;
1449
1525
  for (const mesh of tracking.items) triangles += controllers.get(mesh)?.triangles ?? 0;
1450
1526
  return triangles;
@@ -1,5 +1,6 @@
1
1
  import { AttachedBindMode, Box3, type Object3D, Quaternion, Vector3 } from "three";
2
2
  import type { Mesh, SkinnedMesh } from "three";
3
+ import { sphereBoundsHook } from "./engine-hooks.js";
3
4
 
4
5
  /**
5
6
  * Brings every attached-mode skinned mesh under `root` to the bind state the renderer would give it.
@@ -414,11 +415,35 @@ function getEnvelope(
414
415
  * read one world-matrix translation per contributing bone and allocate nothing. The returned
415
416
  * object is cached for the root and updated in place; copy it if it must outlive the next call.
416
417
  */
418
+ /** PRD-898 J4: which envelope's spheres the engine holds for each root. */
419
+ const engineEnvelope = new WeakMap<Object3D, IPosedBoundsEnvelope>();
420
+
417
421
  export function posedBounds(root: Object3D, meshes?: readonly Object3D[]): IThreePoseBounds {
418
422
  const envelope = getEnvelope(root, meshes);
419
- root.updateWorldMatrix(true, true);
420
- rawBounds(envelope, envelope.raw);
421
423
  const raw = envelope.raw;
424
+ // PRD-898 J4: on the owned engine the matrix pass and every sphere read are one call.
425
+ const engine = sphereBoundsHook(root);
426
+ if (engine === undefined) {
427
+ root.updateWorldMatrix(true, true);
428
+ rawBounds(envelope, raw);
429
+ } else {
430
+ // The engine keeps one sphere set per root: hand this envelope's over when it is not the one held.
431
+ if (engineEnvelope.get(root) !== envelope) {
432
+ engine.attach.call(
433
+ root,
434
+ [...envelope.bones.map((s) => s.bone), ...envelope.statics.map((s) => s.object)],
435
+ [...envelope.bones.map((s) => s.radius), ...envelope.statics.map((s) => s.radius)],
436
+ );
437
+ engineEnvelope.set(root, envelope);
438
+ }
439
+ const box = engine.bounds.call(root);
440
+ raw.minX = box[0] ?? Number.POSITIVE_INFINITY;
441
+ raw.minY = box[1] ?? Number.POSITIVE_INFINITY;
442
+ raw.minZ = box[2] ?? Number.POSITIVE_INFINITY;
443
+ raw.maxX = box[3] ?? Number.NEGATIVE_INFINITY;
444
+ raw.maxY = box[4] ?? Number.NEGATIVE_INFINITY;
445
+ raw.maxZ = box[5] ?? Number.NEGATIVE_INFINITY;
446
+ }
422
447
  const min = envelope.result.min;
423
448
  const max = envelope.result.max;
424
449
  const size = envelope.result.size;
@@ -140,6 +140,7 @@ const normal = new Vector3();
140
140
  * @situation scatter fallen logs, twigs, leaf litter, stones and ferns over a forest floor
141
141
  * @situation stream instanced props of any baked mesh round the player without one draw per prop
142
142
  * @situation place rocks, debris or plants on a heightfield with distance thinning and level of detail
143
+ * @alias scatter rocks, debris and plants over terrain
143
144
  * @constraint call `update(follow)` once per rendered frame
144
145
  * @constraint `place` runs once per candidate per tile build: return false for paths and clearings
145
146
  * @constraint rotating or scaling the field is not supported; translating it is