@woosh/meep-engine 3.52.0 → 3.53.0

package/src/engine/graphics3/prefab/prefab_instantiate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prefab_instantiate.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/prefab/prefab_instantiate.js"],"names":[],"mappings":"AAyCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,2CARW,MAAM,WACN,sBAAsB,QACtB,MAAM;IAEY,SAAS,GAA3B,OAAO;IAEL,cAAc,CA+J1B;AAED;;;;;;;;;;;;;;GAcG;AACH,iDAHW,sBAAsB,YACtB,cAAc,QAiBxB;qBAxPY,OAAO,aAAa,EAAE,MAAM;qCAC5B,OAAO,qCAAqC,EAAE,sBAAsB;+BAJlD,qBAAqB"}
+{"version":3,"file":"prefab_instantiate.d.ts","sourceRoot":"","sources":["../../../../../src/engine/graphics3/prefab/prefab_instantiate.js"],"names":[],"mappings":"AA+CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,2CARW,MAAM,WACN,sBAAsB,QACtB,MAAM;IAEY,SAAS,GAA3B,OAAO;IAEL,cAAc,CA8L1B;AAED;;;;;;;;;;;;;;GAcG;AACH,iDAHW,sBAAsB,YACtB,cAAc,QAqBxB;qBA5RY,OAAO,aAAa,EAAE,MAAM;qCAC5B,OAAO,qCAAqC,EAAE,sBAAsB;+BAJlD,qBAAqB"}

package/src/engine/graphics3/prefab/prefab_instantiate.js

@@ -1,5 +1,9 @@
 import { assert } from "../../../core/assert.js";
 import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
+import { PI2 } from "../../../core/math/PI2.js";
+import { seededRandom } from "../../../core/math/random/seededRandom.js";
+import { FoliageWindJoint } from "../../../shade/renderer/animation/foliage/FoliageWindJoint.js";
+import { FoliageWindRig } from "../../../shade/renderer/animation/foliage/FoliageWindRig.js";
 import { ShadeAnimationChannel } from "../../../shade/renderer/animation/ShadeAnimationChannel.js";
 import { ShadeAnimationClip } from "../../../shade/renderer/animation/ShadeAnimationClip.js";
 import { SerializationMetadata } from "../../ecs/components/SerializationMetadata.js";
@@ -13,6 +17,7 @@ import { MeshSkin } from "../../graphics/ecs/mesh-v2/MeshSkin.js";
 import { ShadedGeometry } from "../../graphics/ecs/mesh-v2/ShadedGeometry.js";
 import { ShadedGeometryFlags } from "../../graphics/ecs/mesh-v2/ShadedGeometryFlags.js";
 import { AnimationClips } from "../animation/AnimationClips.js";
+import { FoliageWindRigs } from "../animation/FoliageWindRigs.js";
 import { PrefabInstance } from "./PrefabInstance.js";
 
 /**
@@ -37,6 +42,7 @@ const COMPONENT_TYPES = [
     ParentEntity,
     SerializationMetadata,
     AnimationClips,
+    FoliageWindRigs,
 ];
 
 /**
@@ -96,6 +102,7 @@ export function prefab_instantiate(prefab, dataset, root, { transient = true } =
     const PARENT = dataset.computeComponentTypeIndex(ParentEntity);
     const METADATA = dataset.computeComponentTypeIndex(SerializationMetadata);
     const CLIPS = dataset.computeComponentTypeIndex(AnimationClips);
+    const FOLIAGE_RIGS = dataset.computeComponentTypeIndex(FoliageWindRigs);
 
     const root_transform = dataset.getComponent(root, Transform64);
 
@@ -231,6 +238,36 @@ export function prefab_instantiate(prefab, dataset, root, { transient = true } =
     // then.
     dataset.addComponentToEntityByIndex(root, CLIPS, AnimationClips.from(clips));
 
+    if (Array.isArray(prefab.foliage_rigs) && prefab.foliage_rigs.length > 0) {
+        const tx = root_transform.matrix[12];
+        const ty = root_transform.matrix[13];
+        const tz = root_transform.matrix[14];
+        const pos_hash = Math.imul(Math.round(tx * 100), 73856093)
+            ^ Math.imul(Math.round(ty * 100), 19349663)
+            ^ Math.imul(Math.round(tz * 100), 83492791)
+            ^ root;
+        const phase_rng = seededRandom(pos_hash | 0);
+        const phase_offset = phase_rng() * PI2;
+
+        const rigs = prefab.foliage_rigs.map(rig => FoliageWindRig.from({
+            name: rig.name,
+            root: entities[rig.root],
+            weight: rig.weight,
+            joints: rig.joints.map(joint => FoliageWindJoint.from({
+                target: entities[joint.target],
+                branch_axis: joint.branch_axis,
+                compliance: joint.compliance,
+                natural_frequency: joint.natural_frequency,
+                damping_ratio: joint.damping_ratio,
+                max_angle: joint.max_angle,
+                turbulence: joint.turbulence,
+                phase_offset: (joint.phase_offset + phase_offset) % PI2,
+            })),
+        }));
+
+        dataset.addComponentToEntityByIndex(root, FOLIAGE_RIGS, FoliageWindRigs.from(rigs));
+    }
+
     return instance;
 }
 
@@ -253,14 +290,18 @@ export function prefab_instance_destroy(dataset, instance) {
     assert.defined(dataset, 'dataset');
     assert.defined(instance, 'instance');
 
+    const root = instance.root;
+
+    if (dataset.entityExists(root) && dataset.getComponent(root, FoliageWindRigs) !== undefined) {
+        dataset.removeComponentFromEntity(root, FoliageWindRigs);
+    }
+
     const entities = instance.entities;
 
     for (let i = entities.length - 1; i >= 1; i--) {
         dataset.removeEntity(entities[i]);
     }
 
-    const root = instance.root;
-
     if (dataset.entityExists(root) && dataset.getComponent(root, AnimationClips) !== undefined) {
         dataset.removeComponentFromEntity(root, AnimationClips);
     }

package/src/engine/graphics3/terrain/chunk_terrain_material_surface.js

@@ -31,8 +31,8 @@ fn material_surface(s: MaterialSurfaceInput) -> MaterialSurfaceOutput {
     // the terrain is an axis-aligned field in its own space: uv is a division, not a mapping
     let terrain_uv = s.position_os.xz * terrain.inv_world_size;
 
-    let duv_dx = s.position_os_ddx.xz * terrain.inv_world_size;
-    let duv_dy = s.position_os_ddy.xz * terrain.inv_world_size;
+    let duv_dx = s.position_os_ddx.xz * terrain.inv_world_size * s.gradient_bias.x;
+    let duv_dy = s.position_os_ddy.xz * terrain.inv_world_size * s.gradient_bias.y;
 
     var ground = terrain_splat_mix(
         layer_diffuse, layer_sampler,

package/src/engine/physics/ecs/ContactProbeSystem.d.ts

@@ -15,7 +15,7 @@
 export class ContactProbeSystem extends System<any> {
     constructor();
     dependencies: (typeof TransformAttachment | typeof ContactProbe)[];
-    components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof AnimationGraphController> | ResourceAccessSpecification<typeof Animation> | ResourceAccessSpecification<typeof TransformAttachment> | ResourceAccessSpecification<typeof GPUStateAuthority> | ResourceAccessSpecification<typeof ParentEntity> | ResourceAccessSpecification<typeof ContactProbe>)[];
+    components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof TransformAttachment> | ResourceAccessSpecification<typeof GPUStateAuthority> | ResourceAccessSpecification<typeof ParentEntity> | ResourceAccessSpecification<typeof AnimationClips> | ResourceAccessSpecification<typeof ContactProbe>)[];
     /**
      * @param {ContactProbe} probe
      * @param {TransformAttachment} attachment
@@ -37,8 +37,7 @@ import { ContactProbe } from "./ContactProbe.js";
 import { Transform64 } from "../../ecs/transform/Transform64.js";
 import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
 import { Collider } from "./Collider.js";
-import { AnimationGraphController } from "../../graphics3/animation/AnimationGraphController.js";
-import { Animation } from "../../ecs/animation/Animation.js";
 import { GPUStateAuthority } from "../../ecs/gpu/GPUStateAuthority.js";
 import { ParentEntity } from "../../ecs/parent/ParentEntity.js";
+import { AnimationClips } from "../../graphics3/animation/AnimationClips.js";
 //# sourceMappingURL=ContactProbeSystem.d.ts.map

package/src/engine/physics/ecs/ContactProbeSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ContactProbeSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/ContactProbeSystem.js"],"names":[],"mappings":"AAsEA;;;;;;;;;;;;;GAaG;AACH;;IAEI,mEAAmD;IAEnD,2bASE;IAyCF;;;;OAIG;IACH,YAJW,YAAY,cACZ,mBAAmB,UACnB,MAAM,QAUhB;IAED;;;;OAIG;IACH,cAJW,YAAY,cACZ,mBAAmB,UACnB,MAAM,QAWhB;IAED,sCA2BC;;CAiKJ;uBA1VsB,qBAAqB;oCAER,uDAAuD;6BAY9D,mBAAmB;4BALzC,oCAAoC;4CAdC,oDAAoD;yBAkBvE,eAAe;yCAHC,uDAAuD;0BAdtE,kCAAkC;kCAC1B,oCAAoC;6BACzC,kCAAkC"}
+{"version":3,"file":"ContactProbeSystem.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/ContactProbeSystem.js"],"names":[],"mappings":"AAqEA;;;;;;;;;;;;;GAaG;AACH;;IAEI,mEAAmD;IAEnD,iYAQE;IAyCF;;;;OAIG;IACH,YAJW,YAAY,cACZ,mBAAmB,UACnB,MAAM,QAUhB;IAED;;;;OAIG;IACH,cAJW,YAAY,cACZ,mBAAmB,UACnB,MAAM,QAWhB;IAED,sCA2BC;;CAiKJ;uBAzVsB,qBAAqB;oCAER,uDAAuD;6BAY9D,mBAAmB;4BALzC,oCAAoC;4CAbC,oDAAoD;yBAiBvE,eAAe;kCAhBN,oCAAoC;6BACzC,kCAAkC;+BAYhC,6CAA6C"}

package/src/engine/physics/ecs/ContactProbeSystem.js

@@ -5,7 +5,6 @@ import { SphereShape3D } from "../../../core/geom/3d/shape/SphereShape3D.js";
 import { v3_quaternion_apply } from "../../../core/geom/vec3/v3_quaternion_apply.js";
 import { ResourceAccessKind } from "../../../core/model/ResourceAccessKind.js";
 import { ResourceAccessSpecification } from "../../../core/model/ResourceAccessSpecification.js";
-import { Animation } from "../../ecs/animation/Animation.js";
 import { GPUStateAuthority } from "../../ecs/gpu/GPUStateAuthority.js";
 import { ParentEntity } from "../../ecs/parent/ParentEntity.js";
 import { parent_entity_model_of } from "../../ecs/parent/parent_entity_model_of.js";
@@ -19,7 +18,7 @@ import {
     TRANSFORM64_SCALE_OFFSET,
     TRANSFORM64_TRANSLATION_OFFSET
 } from "../../ecs/transform/Transform64.js";
-import { AnimationGraphController } from "../../graphics3/animation/AnimationGraphController.js";
+import { AnimationClips } from "../../graphics3/animation/AnimationClips.js";
 import { collect_entity_playbacks } from "../../graphics3/pose/collect_entity_playbacks.js";
 import { PhysicsSurfacePoint } from "../queries/PhysicsSurfacePoint.js";
 import { Collider } from "./Collider.js";
@@ -93,8 +92,7 @@ export class ContactProbeSystem extends System {
         ResourceAccessSpecification.from(GPUStateAuthority, ResourceAccessKind.Read),
         ResourceAccessSpecification.from(ParentEntity, ResourceAccessKind.Read),
         ResourceAccessSpecification.from(Collider, ResourceAccessKind.Read),
-        ResourceAccessSpecification.from(Animation, ResourceAccessKind.Read),
-        ResourceAccessSpecification.from(AnimationGraphController, ResourceAccessKind.Read),
+        ResourceAccessSpecification.from(AnimationClips, ResourceAccessKind.Read),
     ];
 
     /**

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -66,11 +66,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#462@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#464@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#462@#clear_field"(fluid: FluidComponent): void;
+    static "__#464@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -82,7 +82,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#462@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#464@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -102,7 +102,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#462@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#464@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof FluidObstacle> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof FluidComponent>)[];

package/src/engine/sound/simulation/PROBE_PLACEMENT.md

@@ -186,7 +186,7 @@ keep a back-compat shim or migrate callers. Serialization (positions-only) is un
 
 ## As-built (landed)
 
-All four stages shipped; `bakeProbeField(index, minSpacing, rayCount, random, options)` now runs
+All four stages shipped; `bakeProbeField({ index, minSpacing, rayCount, random, ... })` now runs
 **SDF grid → portal discovery → cover (portals pre-seeded) → connectivity refinement → reverb** instead of the
 blind grid. The bake REGION is derived from the scene — the occluder hull
 (`AcousticOccluderIndex.computeWorldBounds`) inflated by `2 × minSpacing` on every side — not a caller
@@ -194,8 +194,8 @@ parameter; a caller wanting a hand-picked region drops to `build_sdf_grid` + `pr
 
 - **Stage 0** `AcousticOccluderIndex.signedDistanceAt(x,y,z,maxDistance)` — union SDF via the body-AABB BVH +
   per-body `shape.signed_distance_at_point` (negative inside, clamped to `+maxDistance`).
-- **Grid** `build_sdf_grid(index, bounds, minSpacing, sparsenessRatio)` (`probe_sdf_grid.js`) — the SDF voxel
-  grid (oversampled 2× below `minSpacing`, capped 256³) is built ONCE and shared by the cover and (implicitly,
+- **Grid** `build_sdf_grid({ index, bounds, minSpacing, sparsenessRatio, oversample, resolutionLimit })` (`probe_sdf_grid.js`) — the SDF voxel
+  grid (oversampled 2× below `minSpacing`, capped 256³ by default) is built ONCE and shared by the cover and (implicitly,
   via the same `signedDistanceAt`) portal detection, so the expensive up-to-256³ SDF sweep is paid once. The
   trilinear sampler, gradient-ascent local-max, and claim-sphere helpers live here too.
 - **Stage 1** `probe_place_sdf_cover(grid, {predefined})` — SDF maximal-empty-sphere greedy cover. Erase radius
@@ -235,7 +235,7 @@ parameter; a caller wanting a hand-picked region drops to `build_sdf_grid` + `pr
 - **The grid jitter** added to the old `bakeProbeField` is now moot (no grid) and was removed in the rewrite;
   the cover's gradient-ascended points are already general-position for the Delaunay base.
 
-Knobs (all in `options`, JSDoc'd): `sparsenessRatio`, `maxRefineFactor`, `corridorReachFactor`,
+Knobs (all top-level parameters in `bakeProbeField`, JSDoc'd): `sdfSparsenessRatio`, `sdfOversample`, `sdfResolutionLimit`, `maxRefineFactor`, `corridorReachFactor`,
 `maxRefineRounds`, `detectPortals` (default true), `constrictionFactor`, `portalFloorRatio`. Tests:
 `core/signedDistanceAt.spec.js`, `probe/probe_place_sdf_cover.spec.js`, `probe/probe_refine_connectivity.spec.js`,
 `probe/probe_detect_portals.spec.js`, `probe/probe_densify_portals.spec.js`, the end-to-end

package/src/engine/sound/simulation/README.md

@@ -141,7 +141,7 @@ import { seededRandom } from "../../../core/math/random/seededRandom.js";
 
 // OFFLINE: place probes over the scene (the bake region is derived from the occluder hull) and bake each
 // probe's per-band RT60. minSpacing is the density knob (smaller = denser).
-const probes = bakeProbeField(sim.occluderIndex, /*minSpacing*/ 8, /*rayCount*/ 256, seededRandom(1));
+const probes = bakeProbeField({ index: sim.occluderIndex, minSpacing: 8, rayCount: 256, random: seededRandom(1) });
 const json = probes.toJSON();   // serialize, ship as an asset
 
 // RUNTIME: an acoustic-owned reverb bus driven by the listener's nearest probe

package/src/engine/sound/simulation/probe/bakeProbeField.d.ts

@@ -29,16 +29,30 @@
  *
  * The `minSpacing` hint drives the initial cover/fit; only connectivity refinement may go finer.
  *
- * @param {AcousticOccluderIndex} index the acoustic scene (its occluder hull defines the bake region)
- * @param {number} minSpacing target/min probe spacing — the density hint (smaller = denser)
- * @param {number} rayCount rays per probe (reverb estimate quality)
- * @param {function():number} random seeded RNG (reverb bake)
- * @param {{sparsenessRatio?: number, maxRefineFactor?: number, corridorReachFactor?: number, maxRefineRounds?: number, detectPortals?: boolean, constrictionFactor?: number, portalFloorRatio?: number}} [options]
- *        `detectPortals` (default true) toggles the portal discovery + densification stages.
+ * @param {Object} options
+ * @param {AcousticOccluderIndex} options.index the acoustic scene (its occluder hull defines the bake region)
+ * @param {number} options.minSpacing target/min probe spacing — the density hint (smaller = denser)
+ * @param {number} options.rayCount rays per probe (reverb estimate quality)
+ * @param {function():number} options.random seeded RNG (reverb bake)
+ * @param {number} [options.sdfSparsenessRatio]
+ * @param {number} [options.sdfOversample]
+ * @param {number} [options.sdfResolutionLimit]
+ * @param {number} [options.maxRefineFactor]
+ * @param {number} [options.corridorReachFactor]
+ * @param {number} [options.maxRefineRounds]
+ * @param {boolean} [options.detectPortals] (default true) toggles the portal discovery + densification stages
+ * @param {number} [options.constrictionFactor]
+ * @param {number} [options.portalFloorRatio]
  * @returns {AcousticProbeField}
  */
-export function bakeProbeField(index: AcousticOccluderIndex, minSpacing: number, rayCount: number, random: () => number, options?: {
-    sparsenessRatio?: number;
+export function bakeProbeField({ index, minSpacing, rayCount, random, sdfSparsenessRatio, sdfOversample, sdfResolutionLimit, maxRefineFactor, corridorReachFactor, maxRefineRounds, detectPortals, constrictionFactor, portalFloorRatio, }: {
+    index: AcousticOccluderIndex;
+    minSpacing: number;
+    rayCount: number;
+    random: () => number;
+    sdfSparsenessRatio?: number;
+    sdfOversample?: number;
+    sdfResolutionLimit?: number;
     maxRefineFactor?: number;
     corridorReachFactor?: number;
     maxRefineRounds?: number;

package/src/engine/sound/simulation/probe/bakeProbeField.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bakeProbeField.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/bakeProbeField.js"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,yEAPW,MAAM,YACN,MAAM,gBACK,MAAM,YACjB;IAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAC,GAE3L,kBAAkB,CA+E9B;mCAtJkC,yBAAyB"}
+{"version":3,"file":"bakeProbeField.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/bakeProbeField.js"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH;IAf0C,KAAK;IACpB,UAAU,EAA1B,MAAM;IACU,QAAQ,EAAxB,MAAM;IACqB,MAAM,QAAtB,MAAM;IACA,kBAAkB,GAAnC,MAAM;IACW,aAAa,GAA9B,MAAM;IACW,kBAAkB,GAAnC,MAAM;IACW,eAAe,GAAhC,MAAM;IACW,mBAAmB,GAApC,MAAM;IACW,eAAe,GAAhC,MAAM;IACY,aAAa,GAA/B,OAAO;IACU,kBAAkB,GAAnC,MAAM;IACW,gBAAgB,GAAjC,MAAM;IACJ,kBAAkB,CAyG9B;mCAxLkC,yBAAyB"}

package/src/engine/sound/simulation/probe/bakeProbeField.js

@@ -65,15 +65,37 @@ const LOBE_SCRATCH = new Float32Array(MAX_LOBES * LOBE_STRIDE);
  *
  * The `minSpacing` hint drives the initial cover/fit; only connectivity refinement may go finer.
  *
- * @param {AcousticOccluderIndex} index the acoustic scene (its occluder hull defines the bake region)
- * @param {number} minSpacing target/min probe spacing — the density hint (smaller = denser)
- * @param {number} rayCount rays per probe (reverb estimate quality)
- * @param {function():number} random seeded RNG (reverb bake)
- * @param {{sparsenessRatio?: number, maxRefineFactor?: number, corridorReachFactor?: number, maxRefineRounds?: number, detectPortals?: boolean, constrictionFactor?: number, portalFloorRatio?: number}} [options]
- *        `detectPortals` (default true) toggles the portal discovery + densification stages.
+ * @param {Object} options
+ * @param {AcousticOccluderIndex} options.index the acoustic scene (its occluder hull defines the bake region)
+ * @param {number} options.minSpacing target/min probe spacing — the density hint (smaller = denser)
+ * @param {number} options.rayCount rays per probe (reverb estimate quality)
+ * @param {function():number} options.random seeded RNG (reverb bake)
+ * @param {number} [options.sdfSparsenessRatio]
+ * @param {number} [options.sdfOversample]
+ * @param {number} [options.sdfResolutionLimit]
+ * @param {number} [options.maxRefineFactor]
+ * @param {number} [options.corridorReachFactor]
+ * @param {number} [options.maxRefineRounds]
+ * @param {boolean} [options.detectPortals] (default true) toggles the portal discovery + densification stages
+ * @param {number} [options.constrictionFactor]
+ * @param {number} [options.portalFloorRatio]
  * @returns {AcousticProbeField}
  */
-export function bakeProbeField(index, minSpacing, rayCount, random, options = {}) {
+export function bakeProbeField({
+    index,
+    minSpacing,
+    rayCount,
+    random,
+    sdfSparsenessRatio,
+    sdfOversample,
+    sdfResolutionLimit,
+    maxRefineFactor,
+    corridorReachFactor,
+    maxRefineRounds = DEFAULT_MAX_REFINE_ROUNDS,
+    detectPortals = true,
+    constrictionFactor,
+    portalFloorRatio,
+}) {
     // Derive the bake region from the scene: the occluder hull + a spacing-scaled margin. No occluders →
     // nothing to cover → an empty field.
     if (index.computeWorldBounds(HULL) === 0) {
@@ -87,16 +109,26 @@ export function bakeProbeField(index, minSpacing, rayCount, random, options = {}
 
     // The SDF grid is the expensive part (up to 256³ signedDistanceAt queries); build it once and reuse it for
     // both the provisional and the final cover.
-    const grid = build_sdf_grid(index, bounds, minSpacing, options.sparsenessRatio);
+    const grid = build_sdf_grid({
+        index,
+        bounds,
+        minSpacing,
+        sparsenessRatio: sdfSparsenessRatio,
+        oversample: sdfOversample,
+        resolutionLimit: sdfResolutionLimit,
+    });
 
     // 1. Portal discovery — a provisional cover + visibility resolves the openings (a doorway is sub-voxel, so
     //    it is found from the graph's BVH visibility rays, not the grid), then detect each opening's throat.
     const provisional = new AcousticProbeField();
     placeProbes(provisional, probe_place_sdf_cover(grid));
     bakeVisibility(provisional, index);
-    const portals = options.detectPortals === false
+    const portals = !detectPortals
         ? NO_PORTALS
-        : probe_detect_portals(provisional, index, minSpacing, options);
+        : probe_detect_portals(provisional, index, minSpacing, {
+            constrictionFactor,
+            portalFloorRatio,
+        });
 
     // 2. Final cover — re-place with the portal throats PRE-SEEDED so they carve the SDF (no redundant cover
     //    probe lands on them) and lead the probe list (indices [0, portalCount)). Densify the visibility around
@@ -115,9 +147,11 @@ export function bakeProbeField(index, minSpacing, rayCount, random, options = {}
 
     // 3. Connectivity refinement — thread bends/throats so a visible probe chain spans every acoustic path.
     //    Inserted waypoints append AFTER the cover, so the portals stay at [0, portalCount).
-    const maxRounds = options.maxRefineRounds ?? DEFAULT_MAX_REFINE_ROUNDS;
-    for (let round = 0; round < maxRounds; round++) {
-        const waypoints = probe_refine_connectivity(index, field, minSpacing, options);
+    for (let round = 0; round < maxRefineRounds; round++) {
+        const waypoints = probe_refine_connectivity(index, field, minSpacing, {
+            maxRefineFactor,
+            corridorReachFactor,
+        });
         if (waypoints.length === 0) {
             break;
         }
@@ -152,14 +186,25 @@ export function bakeProbeField(index, minSpacing, rayCount, random, options = {}
     return field;
 }
 
-/** Append a flat `[x,y,z, …]` list of positions to the field as probes. */
+/**
+ * Append a flat `[x,y,z, …]` list of positions to the field as probes.
+ *
+ * @param {AcousticProbeField} field
+ * @param {ArrayLike<number>} positions
+ * @returns {void}
+ */
 function placeProbes(field, positions) {
     for (let i = 0; i < positions.length; i += 3) {
         field.setProbePosition(field.size, positions[i], positions[i + 1], positions[i + 2]);
     }
 }
 
-/** The index range `[0, count)` — the indices of the pre-seeded portal probes (placed first). */
+/**
+ * The index range `[0, count)` — the indices of the pre-seeded portal probes (placed first).
+ *
+ * @param {number} count
+ * @returns {Uint32Array}
+ */
 function indexRange(count) {
     const out = new Uint32Array(count);
     for (let i = 0; i < count; i++) {

package/src/engine/sound/simulation/probe/bakeProbeReflectors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bakeProbeReflectors.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/bakeProbeReflectors.js"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;GAaG;AACH,qEARW,MAAM,KACN,MAAM,KACN,MAAM,UACN,MAAM,YACN,MAAM,YACN,YAAY,GACV,MAAM,CA+DlB;AA9FD,0BAAoB"}
+{"version":3,"file":"bakeProbeReflectors.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/bakeProbeReflectors.js"],"names":[],"mappings":"AAqCA;;;;;;;;;;;;;GAaG;AACH,qEARW,MAAM,KACN,MAAM,KACN,MAAM,UACN,MAAM,YACN,MAAM,YACN,YAAY,GACV,MAAM,CAsDlB;AAnFD,0BAAoB"}

package/src/engine/sound/simulation/probe/bakeProbeReflectors.js

@@ -1,5 +1,12 @@
 import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
 import { sphere_fibonacci_point } from "../../../../core/geom/3d/sphere/sphere_fibonacci_point.js";
+import { v3_add } from "../../../../core/geom/vec3/v3_add.js";
+import { v3_add_array } from "../../../../core/geom/vec3/v3_add_array.js";
+import { v3_dot } from "../../../../core/geom/vec3/v3_dot.js";
+import { v3_length } from "../../../../core/geom/vec3/v3_length.js";
+import { v3_normalize_array } from "../../../../core/geom/vec3/v3_normalize_array.js";
+import { v3_scale_array } from "../../../../core/geom/vec3/v3_scale_array.js";
+import { v3_set } from "../../../../core/geom/vec3/v3_set.js";
 import { RayHit } from "../core/RayHit.js";
 import { LOBE_STRIDE } from "./acoustic_probe_transfer.js";
 
@@ -24,9 +31,7 @@ const RAY = new Ray3();
 const HIT = new RayHit();
 const FIB = [0, 0, 0];
 // per-cluster accumulators (summed normal, summed per-band ρ, sample count)
-const C_NX = new Float32Array(MAX_LOBES);
-const C_NY = new Float32Array(MAX_LOBES);
-const C_NZ = new Float32Array(MAX_LOBES);
+const C_NORMAL = new Float32Array(MAX_LOBES * 3);
 const C_RHO = new Float32Array(MAX_LOBES * 3);
 const C_COUNT = new Float32Array(MAX_LOBES);
 
@@ -59,15 +64,14 @@ export function bakeProbeReflectors(index, x, y, z, radius, rayCount, outLobes)
         }
 
         const nx = HIT.normal[0], ny = HIT.normal[1], nz = HIT.normal[2];
-        const a = HIT.material.absorption;
-        const r0 = 1 - a[0], r1 = 1 - a[1], r2 = 1 - a[2]; // per-band reflectivity
 
         // assign to the first cluster whose mean normal agrees within CLUSTER_COS, else open a new one
         let c = -1;
         for (let k = 0; k < nClusters; k++) {
-            const sx = C_NX[k], sy = C_NY[k], sz = C_NZ[k];
-            const slen = Math.sqrt(sx * sx + sy * sy + sz * sz);
-            if (slen > 0 && (nx * sx + ny * sy + nz * sz) / slen > CLUSTER_COS) {
+            const k3 = k * 3;
+            const sx = C_NORMAL[k3], sy = C_NORMAL[k3 + 1], sz = C_NORMAL[k3 + 2];
+            const slen = v3_length(sx, sy, sz);
+            if (slen > 0 && v3_dot(nx, ny, nz, sx, sy, sz) / slen > CLUSTER_COS) {
                 c = k;
                 break;
             }
@@ -77,31 +81,23 @@ export function bakeProbeReflectors(index, x, y, z, radius, rayCount, outLobes)
                 continue; // cluster budget exhausted — drop the extra reflector
             }
             c = nClusters++;
-            C_NX[c] = 0; C_NY[c] = 0; C_NZ[c] = 0;
-            C_RHO[c * 3] = 0; C_RHO[c * 3 + 1] = 0; C_RHO[c * 3 + 2] = 0;
+            v3_set(C_NORMAL, c * 3, 0, 0, 0);
+            v3_set(C_RHO, c * 3, 0, 0, 0);
             C_COUNT[c] = 0;
         }
 
-        C_NX[c] += nx; C_NY[c] += ny; C_NZ[c] += nz;
-        C_RHO[c * 3] += r0; C_RHO[c * 3 + 1] += r1; C_RHO[c * 3 + 2] += r2;
+        const a = HIT.material.absorption;
+        v3_add_array(C_NORMAL, c * 3, HIT.normal, 0);
+        v3_add(C_RHO, c * 3, 1 - a[0], 1 - a[1], 1 - a[2]); // per-band reflectivity
         C_COUNT[c]++;
     }
 
     // finalize each cluster into a lobe: unit mean normal + mean reflectivity
     for (let k = 0; k < nClusters; k++) {
-        const cnt = C_COUNT[k];
-        const sx = C_NX[k], sy = C_NY[k], sz = C_NZ[k];
-        const slen = Math.sqrt(sx * sx + sy * sy + sz * sz);
-        const inv = slen > 0 ? 1 / slen : 0;
-
         const b = k * LOBE_STRIDE;
-        outLobes[b] = sx * inv;
-        outLobes[b + 1] = sy * inv;
-        outLobes[b + 2] = sz * inv;
+        v3_normalize_array(outLobes, b, C_NORMAL, k * 3);
         outLobes[b + 3] = LOBE_LAMBDA;
-        outLobes[b + 4] = C_RHO[k * 3] / cnt;
-        outLobes[b + 5] = C_RHO[k * 3 + 1] / cnt;
-        outLobes[b + 6] = C_RHO[k * 3 + 2] / cnt;
+        v3_scale_array(outLobes, b + 4, C_RHO, k * 3, 1 / C_COUNT[k]);
     }
 
     return nClusters;

package/src/engine/sound/simulation/probe/probe_sdf_grid.d.ts

@@ -15,20 +15,48 @@
  */
 /**
  * Build a signed distance field on a voxel grid over `bounds` by sampling
- * {@link AcousticOccluderIndex#signedDistanceAt}. The grid is finer than `minSpacing` (by {@link OVERSAMPLE})
- * so it resolves sub-spacing features, and capped at {@link RESOLUTION_LIMIT}³.
+ * {@link AcousticOccluderIndex#signedDistanceAt}. The grid is finer than `minSpacing` (by `oversample`,
+ * default {@link DEFAULT_OVERSAMPLE}) so it resolves sub-spacing features, and capped at `resolutionLimit`³
+ * (default {@link DEFAULT_RESOLUTION_LIMIT}³).
  *
- * @param {AcousticOccluderIndex} index the acoustic scene
- * @param {number[]} bounds `[x0,y0,z0,x1,y1,z1]`
- * @param {number} minSpacing the probe spacing hint
- * @param {number} [sparsenessRatio]
+ * @param {Object} options
+ * @param {AcousticOccluderIndex} options.index the acoustic scene
+ * @param {number[]} options.bounds `[x0,y0,z0,x1,y1,z1]`
+ * @param {number} options.minSpacing the probe spacing hint
+ * @param {number} [options.sparsenessRatio]
+ * @param {number} [options.oversample]
+ * @param {number} [options.resolutionLimit]
  * @returns {SdfGrid}
  */
-export function build_sdf_grid(index: AcousticOccluderIndex, bounds: number[], minSpacing: number, sparsenessRatio?: number): SdfGrid;
-/** World position of the (fractional) voxel coordinate `(fx,fy,fz)`, written into `out`. */
-export function grid_voxel_to_world(grid: any, out: any, fx: any, fy: any, fz: any): void;
-/** SDF at a WORLD position via trilinear interpolation of the grid (edge-clamped). */
-export function grid_sample_world(grid: any, x: any, y: any, z: any): number;
+export function build_sdf_grid({ index, bounds, minSpacing, sparsenessRatio, oversample, resolutionLimit, }: {
+    index: AcousticOccluderIndex;
+    bounds: number[];
+    minSpacing: number;
+    sparsenessRatio?: number;
+    oversample?: number;
+    resolutionLimit?: number;
+}): SdfGrid;
+/**
+ * World position of the (fractional) voxel coordinate `(fx,fy,fz)`, written into `out`.
+ *
+ * @param {SdfGrid} grid
+ * @param {number[]|Float32Array} out `[x,y,z]` written here
+ * @param {number} fx
+ * @param {number} fy
+ * @param {number} fz
+ * @returns {void}
+ */
+export function grid_voxel_to_world(grid: SdfGrid, out: number[] | Float32Array, fx: number, fy: number, fz: number): void;
+/**
+ * SDF at a WORLD position via trilinear interpolation of the grid (edge-clamped).
+ *
+ * @param {SdfGrid} grid
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {number}
+ */
+export function grid_sample_world(grid: SdfGrid, x: number, y: number, z: number): number;
 /**
  * Trilinear sample of the SDF grid at fractional voxel coordinates (edge-clamped).
  *
@@ -36,22 +64,40 @@ export function grid_sample_world(grid: any, x: any, y: any, z: any): number;
  * {@link scs3d_sample_linear} samples — so the interpolation is delegated rather than re-derived here.
  * (Same clamp semantics: clamping the COORDINATE into `[0, res-1]` and clamping the two sample INDICES
  * agree on every input, including out-of-range coordinates, where both collapse to the edge voxel.)
+ *
+ * @param {SdfGrid} grid
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @returns {number}
  */
-export function grid_sample_trilinear(grid: any, x: any, y: any, z: any): number;
+export function grid_sample_trilinear(grid: SdfGrid, x: number, y: number, z: number): number;
 /**
  * Gradient-ascend a voxel to the local SDF maximum (the most-open sub-voxel point), written into `out` as a
  * fractional voxel coordinate clamped to within ½ voxel of the start. Central-difference gradient on the
  * trilinearly-sampled SDF; the gradient is not normalised, so steps shrink near the maximum.
+ *
+ * @param {number[]|Float32Array} out `[fx,fy,fz]` written here
+ * @param {SdfGrid} grid
+ * @param {number} vx
+ * @param {number} vy
+ * @param {number} vz
+ * @returns {void}
  */
-export function grid_local_maximum(out: any, grid: any, vx: any, vy: any, vz: any): void;
+export function grid_local_maximum(out: number[] | Float32Array, grid: SdfGrid, vx: number, vy: number, vz: number): void;
 /**
  * Mark every voxel whose centre is within `radius` of the world point `(px,py,pz)` as claimed. O((radius/voxel)³)
  * per call. A degenerate axis (`vs===0`, a zero-extent bake region) claims all its coincident layers.
+ *
+ * @param {Uint8Array} claimed per-voxel claimed flags (`total` elements)
+ * @param {SdfGrid} grid
+ * @param {number} px
+ * @param {number} py
+ * @param {number} pz
+ * @param {number} radius
+ * @returns {void}
  */
-export function grid_claim_sphere(claimed: any, grid: any, px: any, py: any, pz: any, radius: any): void;
-export const OVERSAMPLE: 2;
-export const RESOLUTION_LIMIT: 256;
-export const DEFAULT_SPARSENESS_RATIO: 4;
+export function grid_claim_sphere(claimed: Uint8Array, grid: SdfGrid, px: number, py: number, pz: number, radius: number): void;
 /**
  * A signed distance field sampled on a regular voxel grid over a bake region. Shared by the placement cover
  * ({@link probe_place_sdf_cover }) and portal detection ({@link probe_detect_portals }) so the expensive

package/src/engine/sound/simulation/probe/probe_sdf_grid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"probe_sdf_grid.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/probe_sdf_grid.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;GAUG;AACH,qEALW,MAAM,EAAE,cACR,MAAM,oBACN,MAAM,GACJ,OAAO,CA8CnB;AAED,4FAA4F;AAC5F,0FAIC;AAED,sFAAsF;AACtF,6EAKC;AAED;;;;;;;GAOG;AACH,iFAEC;AAED;;;;GAIG;AACH,yFAqBC;AAED;;;GAGG;AACH,yGAuBC;AArKD,2BAA4B;AAE5B,mCAAoC;AAGpC,yCAA0C;;;;;;;;;;SAW5B,YAAY;QACZ,MAAM;QAAgB,MAAM;;;;QAAgB,MAAM;;;;aAClD,MAAM;;;;WAA6B,MAAM;QACzC,MAAM;QAAgB,MAAM;;;;QAAgB,MAAM;QAClD,MAAM;QAAgB,MAAM;;;;QAAgB,MAAM;SAClD,MAAM;SAAiB,MAAM;;;;SAAiB,MAAM;gBACpD,MAAM;;;;gBAAwB,MAAM;;;;oBACpC,MAAM"}
+{"version":3,"file":"probe_sdf_grid.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/probe_sdf_grid.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;GAcG;AACH;IAR0C,KAAK;IAClB,MAAM,EAAxB,MAAM,EAAE;IACQ,UAAU,EAA1B,MAAM;IACW,eAAe,GAAhC,MAAM;IACW,UAAU,GAA3B,MAAM;IACW,eAAe,GAAhC,MAAM;IACJ,OAAO,CAsDnB;AAED;;;;;;;;;GASG;AACH,0CAPW,OAAO,OACP,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACJ,IAAI,CAMhB;AAED;;;;;;;;GAQG;AACH,wCANW,OAAO,KACP,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAOlB;AAED;;;;;;;;;;;;;GAaG;AACH,4CANW,OAAO,KACP,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;GAWG;AACH,wCAPW,MAAM,EAAE,GAAC,YAAY,QACrB,OAAO,MACP,MAAM,MACN,MAAM,MACN,MAAM,GACJ,IAAI,CAuBhB;AAED;;;;;;;;;;;GAWG;AACH,2CARW,UAAU,QACV,OAAO,MACP,MAAM,MACN,MAAM,MACN,MAAM,UACN,MAAM,GACJ,IAAI,CAyBhB;;;;;;;;;;SAvMa,YAAY;QACZ,MAAM;QAAgB,MAAM;;;;QAAgB,MAAM;;;;aAClD,MAAM;;;;WAA6B,MAAM;QACzC,MAAM;QAAgB,MAAM;;;;QAAgB,MAAM;QAClD,MAAM;QAAgB,MAAM;;;;QAAgB,MAAM;SAClD,MAAM;SAAiB,MAAM;;;;SAAiB,MAAM;gBACpD,MAAM;;;;gBAAwB,MAAM;;;;oBACpC,MAAM"}