avbd-babylon 0.2.0 → 0.4.0

package/dist/babylonAvbd.d.ts

@@ -2,6 +2,18 @@ import type { Vector3, Quaternion } from "@babylonjs/core/Maths/math.vector.js";
 import type { AbstractMesh } from "@babylonjs/core/Meshes/abstractMesh.js";
 import type { Scene } from "@babylonjs/core/scene.js";
 import type { PhysicsShapeType } from "@babylonjs/core/Physics/v2/IPhysicsEnginePlugin.js";
+import type {
+  AvbdSleepOptions,
+  AvbdHeightfieldOptions,
+  AvbdCookedTerrain,
+  AvbdTerrainMaterial,
+} from "./nativeScenes.js";
+export interface AvbdTerrain {
+  readonly bodies: AvbdPhysicsBody[];
+  readonly triangleCount: number;
+  readonly kind: "heightfield" | "static-mesh";
+  dispose(): void;
+}
 export const AvbdShapeType: Readonly<{
   BOX: "box";
   SPHERE: "sphere";
@@ -31,9 +43,11 @@ export interface AvbdWorldOptions {
   maxSyncedBodies?: number;
   broadphase?: "auto" | "grid" | "hploc";
   solverMode?: AvbdSolverMode;
+  /** Automatically batch a closed jointless world of up to 32 bodies. */
+  smallGroups?: boolean;
   bvh?: { rebuildInterval?: number };
-  /** Optional conservative GPU sleeping. Impacts and edits wake the world. */
-  sleeping?: boolean | { speedThreshold?: number; timeThreshold?: number };
+  /** Optional GPU sleeping. Large worlds wake conservative connected groups on impact. */
+  sleeping?: boolean | AvbdSleepOptions;
   maxContactPairs?: number;
   maxContactEvents?: number;
 }
@@ -116,6 +130,17 @@ export class AvbdPhysicsConstraint {
   dispose(): void;
 }
 export class AvbdPhysics {
+  /** Register static collision pieces before initialize(); reserve body capacity. */
+  addHeightfield(options: AvbdHeightfieldOptions): AvbdTerrain;
+  /** Captures the mesh world transform; later mesh edits do not move terrain. */
+  addStaticMesh(
+    mesh: AbstractMesh,
+    options?: AvbdTerrainMaterial & { thickness?: number },
+  ): AvbdTerrain;
+  addTerrain(
+    cooked: AvbdCookedTerrain,
+    options?: AvbdTerrainMaterial,
+  ): AvbdTerrain;
   sphereCast(
     origin: AvbdVector,
     radius: number,
@@ -151,10 +176,9 @@ export class AvbdPhysics {
   readonly solverDecision: AvbdSolverDecision;
   setSolverMode(mode: AvbdSolverMode): AvbdSolverDecision;
   setGravity(gravity: AvbdVector): void;
-  enableSleeping(options?: {
-    speedThreshold?: number;
-    timeThreshold?: number;
-  }): this;
+  enableSleeping(options?: AvbdSleepOptions): this;
+  /** Wake all sleeping bodies and disable automatic sleeping. */
+  disableSleeping(): this;
   initialize(): void;
   step(): void;
   flushCommands(): void;
@@ -281,5 +305,6 @@ export class AvbdPhysicsBody {
     effectiveMass: number;
     sleeping: boolean;
   }>;
+  /** Mesh-origin position; preserves live rotation and velocities when omitted. */
   teleport(position: Vector3, rotation?: Quaternion): this;
 }

package/dist/native.d.ts

@@ -1,2 +1,3 @@
 export * from "./nativeScenes.js";
 export * from "./gpuDevice.js";
+export * from "./solverPipeline.js";

package/dist/native.js

@@ -1 +1 @@
-export { AvbdScene2D, AvbdScene3D, createWebGPUDevice, prepareWebGPUDevice3D } from "./avbd.js";
+export { AvbdScene2D, AvbdScene3D, createWebGPUDevice, prepareWebGPUDevice3D, createSolverPipeline, cookHeightfield, cookStaticMesh } from "./avbd.js";

package/dist/nativeScenes.d.ts

@@ -1,3 +1,8 @@
+import type {
+  AvbdSolverPipeline,
+  AvbdSolver2D,
+  AvbdSolver3D,
+} from "./solverPipeline.js";
 export type AvbdTuple3 = readonly [number, number, number];
 export type AvbdTuple2 = readonly [number, number];
 export interface AvbdQueryOptions {
@@ -22,6 +27,55 @@ export interface AvbdQueryHit<V> {
   center: V;
 }
 export type AvbdQuaternion = readonly [number, number, number, number];
+export interface AvbdTerrainMaterial {
+  friction?: number;
+  restitution?: number;
+  group?: number;
+  collidesWith?: number;
+  mass?: 0;
+}
+export interface AvbdHeightfieldOptions extends AvbdTerrainMaterial {
+  heights: ArrayLike<number>;
+  columns: number;
+  rows: number;
+  spacing?: number | AvbdTuple2;
+  origin?: AvbdTuple3;
+  upAxis?: 0 | 1 | 2;
+  /** Local height below every sample; defaults to the minimum height minus 2. */
+  baseHeight?: number;
+  /** Row-major cells; a nonzero entry leaves a hole. */
+  holes?: ArrayLike<number>;
+}
+export interface AvbdStaticMeshOptions extends AvbdTerrainMaterial {
+  /** World-space xyz triples. */
+  positions: ArrayLike<number>;
+  indices?: ArrayLike<number>;
+  /** Backing behind triangle winding, in world units. Defaults to 0.1. */
+  thickness?: number;
+}
+/** Serializable preprocessing output; can be cooked in a separate worker. */
+export interface AvbdCookedTerrain {
+  kind: "heightfield" | "static-mesh";
+  triangleCount: number;
+  pieces: Array<{
+    shape: object;
+    position: AvbdTuple3;
+    rotation: AvbdQuaternion;
+  }>;
+}
+export interface AvbdNativeTerrain {
+  readonly bodies: AvbdRigid[];
+  readonly triangleCount: number;
+  readonly kind: "heightfield" | "static-mesh";
+  /** Disable collision participation; live indices remain stable. */
+  dispose(): void;
+}
+export function cookHeightfield(
+  options: AvbdHeightfieldOptions,
+): AvbdCookedTerrain;
+export function cookStaticMesh(
+  options: AvbdStaticMeshOptions,
+): AvbdCookedTerrain;
 export interface AvbdNativeState3D {
   position: [number, number, number];
   rotation: [number, number, number, number];
@@ -186,6 +240,13 @@ export interface AvbdGpuParameters2D extends AvbdGpuParameters {
   vbd: boolean;
   vbdStiffness: number;
 }
+/** 3D can retain conservative connected groups between explicit world edits. */
+export interface AvbdSleepOptions {
+  speedThreshold?: number;
+  timeThreshold?: number;
+  /** 3D: automatic for large jointless desktop worlds; false selects whole-world waking. */
+  islands?: boolean;
+}
 export interface AvbdGpuOptions {
   bodyBuffer?: GPUBuffer;
   bodyCapacity?: number;
@@ -193,6 +254,8 @@ export interface AvbdGpuOptions {
   spatialSort?: boolean;
   broadphase?: "auto" | "grid" | "hploc";
   solverMode?: "auto" | "standard" | "optimized" | "points";
+  /** 3D: automatically fuse closed jointless worlds of at most 32 bodies. */
+  smallGroups?: boolean;
   bvh?: { rebuildInterval?: number };
   capacity?: {
     contacts?: number;
@@ -201,9 +264,10 @@ export interface AvbdGpuOptions {
     colors?: number;
     joints?: number;
   };
+  /** Reserve coloring capacity when sleeping bodies wake. */
   minimumColors?: number;
   minimumColorRounds?: number;
-  sleeping?: boolean | { speedThreshold?: number; timeThreshold?: number };
+  sleeping?: boolean | AvbdSleepOptions;
 }
 export interface AvbdGpuSolver {
   readonly bodyBuffer: GPUBuffer;
@@ -273,10 +337,7 @@ export interface AvbdGpuSolver3D extends AvbdGpuSolver {
     rotation?: AvbdQuaternion,
   ): this;
   readBodyState(index: number): Promise<AvbdNativeState3D>;
-  enableSleeping(options?: {
-    speedThreshold?: number;
-    timeThreshold?: number;
-  }): this;
+  enableSleeping(options?: AvbdSleepOptions): this;
   disableSleeping(): this;
   setSleepEnabled(index: number, enabled: boolean): this;
   watchContacts(options?: AvbdNativeContactOptions): this;
@@ -508,6 +569,12 @@ export interface AvbdNativeConstraint {
   destroy(): void;
 }
 export class AvbdScene3D {
+  addHeightfield(options: AvbdHeightfieldOptions): AvbdNativeTerrain;
+  addStaticMesh(options: AvbdStaticMeshOptions): AvbdNativeTerrain;
+  addTerrain(
+    cooked: AvbdCookedTerrain,
+    options?: AvbdTerrainMaterial,
+  ): AvbdNativeTerrain;
   addMotor(
     a: AvbdRigid | null,
     b: AvbdRigid,
@@ -620,6 +687,10 @@ export class AvbdScene3D {
     },
   ): AvbdNativeConstraint;
   createSolver(device: GPUDevice, options?: AvbdGpuOptions): AvbdGpuSolver3D;
+  createSolver(
+    pipeline: AvbdSolverPipeline,
+    options?: AvbdGpuOptions,
+  ): AvbdSolver3D;
 }
 export interface AvbdNativeAngularOptions {
   axisA?: AvbdTuple3;
@@ -729,7 +800,12 @@ export class AvbdScene2D {
       bodyBuffer?: GPUBuffer;
       bodyCapacity?: number;
       colorRounds?: number;
+      minimumColors?: number;
       sleeping?: boolean | { speedThreshold?: number; timeThreshold?: number };
     },
   ): AvbdGpuSolver2D;
+  createSolver(
+    pipeline: AvbdSolverPipeline,
+    options?: AvbdGpuOptions,
+  ): AvbdSolver2D;
 }

package/dist/solverPipeline.d.ts

@@ -0,0 +1,62 @@
+import type {
+  AvbdScene2D,
+  AvbdScene3D,
+  AvbdGpuOptions,
+  AvbdGpuSolver,
+  AvbdGpuSolver2D,
+  AvbdGpuSolver3D,
+  AvbdAdvanceOptions,
+} from "./nativeScenes.js";
+import type { createWebGPUDevice } from "./gpuDevice.js";
+
+export type AvbdSolverBackend = "webgpu" | "cpu";
+/** Shared world settings. GPU scheduling fields apply only to GPU execution. */
+export type AvbdSolverOptions = AvbdGpuOptions;
+/** Drawing buffers belong to the selected backend; simulation operations are shared. */
+type SharedMethods<T, Self> = {
+  [K in keyof T]: T[K] extends (...args: infer A) => infer R
+    ? (...args: A) => R extends AvbdGpuSolver ? Self : R
+    : T[K];
+};
+export interface AvbdSolver2D extends SharedMethods<
+  Omit<AvbdGpuSolver2D, "bodyBuffer" | "shapeBuffer" | "attachToScene">,
+  AvbdSolver2D
+> {
+  readonly backend: AvbdSolverBackend;
+  readonly bodyBuffer?: GPUBuffer;
+  readonly shapeBuffer?: GPUBuffer;
+  attachToScene(
+    scene: Parameters<AvbdGpuSolver2D["attachToScene"]>[0],
+    options?: AvbdAdvanceOptions & {
+      afterStep?: (solver: AvbdSolver2D) => void;
+    },
+  ): this;
+}
+export interface AvbdSolver3D extends SharedMethods<
+  Omit<AvbdGpuSolver3D, "bodyBuffer" | "attachToScene">,
+  AvbdSolver3D
+> {
+  readonly backend: AvbdSolverBackend;
+  readonly bodyBuffer?: GPUBuffer;
+  attachToScene(
+    scene: Parameters<AvbdGpuSolver3D["attachToScene"]>[0],
+    options?: AvbdAdvanceOptions & {
+      afterStep?: (solver: AvbdSolver3D) => void;
+    },
+  ): this;
+}
+export interface AvbdSolverPipeline {
+  readonly backend: AvbdSolverBackend;
+  readonly device?: GPUDevice;
+  readonly adapter?: GPUAdapter;
+  createSolver(scene: AvbdScene2D, options?: AvbdSolverOptions): AvbdSolver2D;
+  createSolver(scene: AvbdScene3D, options?: AvbdSolverOptions): AvbdSolver3D;
+  /** Destroys its worlds and its own device. A supplied device remains caller-owned. */
+  destroy(): void;
+}
+export function createSolverPipeline(
+  options?: NonNullable<Parameters<typeof createWebGPUDevice>[0]> & {
+    backend?: AvbdSolverBackend;
+    device?: GPUDevice;
+  },
+): Promise<AvbdSolverPipeline>;

package/dist/utilities.d.ts

@@ -0,0 +1,161 @@
+/** Nonblocking GPU pass timestamps; null when timestamp-query is unavailable. */
+export class GpuTimer {
+  constructor(device: GPUDevice);
+  readonly latestMs: number | null;
+  readonly samples: number;
+  begin(): object | null;
+  descriptor(slot: object | null): {
+    timestampWrites?: GPUComputePassTimestampWrites;
+  };
+  encode(encoder: GPUCommandEncoder, slot: object | null): void;
+  resolve(slot: object | null): Promise<void> | undefined;
+  settled(): Promise<unknown[]>;
+  destroy(): void;
+}
+/** Reuse released buffers with compatible usage, without CPU pose transfers. */
+export class GPUBufferRecycler {
+  constructor(device: GPUDevice, options?: { maxFreeBytes?: number });
+  readonly freeBytes: number;
+  acquire(
+    byteSize: number,
+    usage: GPUBufferUsageFlags,
+    label?: string,
+  ): GPUBuffer;
+  release(
+    buffer: GPUBuffer,
+    byteSize: number,
+    usage: GPUBufferUsageFlags,
+  ): void;
+  trim(maxFreeBytes?: number): void;
+  destroy(): void;
+}
+export const PARTICLE_BYTE_STRIDE: 48;
+export interface SurfaceParticleStep {
+  dt: number;
+  count?: number;
+  speed?: number;
+  life?: number;
+  bulletRadius?: number;
+  spawnRadius?: number;
+  jitter?: number;
+  frame?: number;
+}
+/** Spherical emitter aimed at the origin. Particles hit triangle surfaces and
+ * respawn; they ignore each other. Five rays approximate the particle sweep. */
+export class GpuSurfaceParticles {
+  constructor(
+    device: GPUDevice,
+    options: { capacity: number; triangleCount: number; readback?: boolean },
+  );
+  readonly device: GPUDevice;
+  readonly capacity: number;
+  readonly triangleCount: number;
+  /** 48 bytes: position/life vec4f, velocity/radius vec4f, seed vec4u. */
+  readonly particleBuffer: GPUBuffer;
+  readonly triangleBuffer: GPUBuffer;
+  readonly counterBuffer: GPUBuffer;
+  readonly timer: GpuTimer;
+  /** 12 float32 values per triangle: [ax,ay,az,0,bx,by,bz,0,cx,cy,cz,0]. */
+  writeTriangles(vertices: Float32Array): void;
+  /** Returns the latest asynchronous counters, or null with readback disabled. */
+  step(options: SurfaceParticleStep): { hits: number; alive: number } | null;
+  clear(): void;
+  destroy(): void;
+}
+export const sampledContactShader: string;
+/** Gather a bounded GPU contact overlay, without reading the full contact set. */
+export class GpuContactSample {
+  constructor(device: GPUDevice, options?: { count?: number });
+  readonly count: number;
+  readonly buffer: GPUBuffer;
+  encode(
+    encoder: GPUCommandEncoder,
+    resources: {
+      bodyBuffer: GPUBuffer;
+      /** Native 3D camera uniform: mat4 vp, vec4 eye, vec4 light/viewport. */
+      cameraBuffer: GPUBuffer;
+      contactStorage: {
+        manifolds: GPUBuffer;
+        contacts: GPUBuffer;
+        counters: GPUBuffer;
+      };
+    },
+  ): void;
+  dispose(): void;
+}
+/** Optional one-time native constraint-graph seed; live GPU coloring still checks contacts. */
+export function seedConstraintColoring(
+  gpu: {
+    device: GPUDevice;
+    bodyCapacity: number;
+    colorBuffer: GPUBuffer;
+    colorCap: number;
+    gpuIndex(index: number): number;
+  },
+  world: {
+    bodies: { mass: number }[];
+    forces: { bodyA: object | null; bodyB: object | null }[];
+  },
+  minimum?: number,
+): void;
+export const INPUT_WORDS: 9;
+/** Custom compute/copy work in the solver's existing command encoder. Callbacks
+ * are synchronous, end their own passes, and must not submit or finish the encoder.
+ * Dispose the registration before destroying its buffers. CPU solvers are rejected. */
+export function addGpuStepPass<
+  T extends { bodyBuffer: GPUBuffer; step(): void },
+>(
+  solver: T,
+  hooks: {
+    before?: (encoder: GPUCommandEncoder, solver: T) => void;
+    after?: (encoder: GPUCommandEncoder, solver: T) => void;
+  },
+): () => void;
+/** DOM-free sizing and event adapter around a caller-owned canvas. */
+export class WorkerCanvas {
+  constructor(
+    canvas: OffscreenCanvas | HTMLCanvasElement,
+    width: number,
+    height: number,
+  );
+  readonly offscreenCanvas: OffscreenCanvas | HTMLCanvasElement;
+  readonly clientWidth: number;
+  readonly clientHeight: number;
+  readonly revision: number;
+  width: number;
+  height: number;
+  resize(width: number, height: number): void;
+  getContext(type: "webgpu"): GPUCanvasContext | null;
+  getContext(type: string, options?: object): unknown;
+  getBoundingClientRect(): {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+  };
+  addEventListener(type: string, callback: (event: any) => void): void;
+  removeEventListener(type: string, callback: (event: any) => void): void;
+  setPointerCapture(): void;
+  dispatch(type: string, data: object): void;
+}
+export interface SharedPointerState {
+  clientX: number;
+  clientY: number;
+  pointerId?: number;
+  buttons?: number;
+  altKey?: boolean;
+  shiftKey?: boolean;
+  ctrlKey?: boolean;
+}
+/** Returns null without cross-origin isolation / SharedArrayBuffer support. */
+export function createSharedInput(): Int32Array<SharedArrayBuffer> | null;
+/** One producer; continuous state only. Send discrete events as ordered messages. */
+export function writeSharedInput(
+  view: Int32Array<SharedArrayBuffer>,
+  event: SharedPointerState,
+  wheel?: number,
+): void;
+export function readSharedInput(
+  view: Int32Array<SharedArrayBuffer>,
+  previous?: number,
+): { sequence: number; event: SharedPointerState; wheel: number } | null;

package/dist/utilities.js

@@ -0,0 +1 @@
+export { GpuTimer, GPUBufferRecycler, GpuSurfaceParticles, PARTICLE_BYTE_STRIDE, GpuContactSample, sampledContactShader, seedConstraintColoring, addGpuStepPass, WorkerCanvas, INPUT_WORDS, createSharedInput, writeSharedInput, readSharedInput } from "./avbd.js";

package/docs/BABYLON_API.md

@@ -1,5 +1,21 @@
 # Babylon.js integration
 
+Static terrain can be added with `physics.addHeightfield(options)` or
+`physics.addStaticMesh(mesh, { thickness, friction, group, collidesWith })`.
+The mesh helper captures current world-space triangles, including parent transforms.
+Both return `{ bodies, triangleCount, kind, dispose() }`. Add terrain before
+`initialize()` or the first render, and reserve body capacity for its collision
+pieces. These pieces do not synchronize meshes each frame. `dispose()` disables
+their collisions while leaving the caller's mesh intact.
+
+Heightfields use two solid prisms per cell. Mesh terrain gives each triangle
+finite backing behind its winding; concavities and overhangs remain open. This
+uses the existing convex contact and grid/HPLOC pipelines. Internal tile edges
+can affect sliding, and a rendering mesh should usually have a simpler collision
+mesh. Terrain is static and does not track subsequent mesh transformations.
+See [terrain examples](../README.md#static-terrain-hills-caves-and-overhangs)
+for the native API, holes, coordinate conventions and worker cooking helpers.
+
 Start with the [integration README](README.md) for a complete scene, bundler setup,
 instance rendering examples and reproducible collision/solver benchmarks.
 
@@ -79,8 +95,10 @@ impacts below 1 m/s do not bounce. Use `body.setRestitution()` for live changes.
 `isTrigger:true` detects dynamic-body overlaps without contact forces;
 `body.setTrigger()` changes the mode. Events include `isTrigger`, and masks
 apply to sensors too. Static–static pairs are not scanned. CCD,
-arbitrary concave meshes and the full Physics V2 plugin
-interface are not implemented. Static bodies given velocity move kinematically.
+dynamic concave meshes and the full Physics V2 plugin
+interface are not implemented. Static triangle meshes and heightfields use
+`addStaticMesh()` and `addHeightfield()` terrain cooking, including caves and
+overhangs. Static bodies given velocity move kinematically.
 
 `addHinge(a,b,{axisA,axisB,anchorA,anchorB,minAngle,maxAngle,motor})` constrains
 rotation to one axis, with optional angle stops and a torque-limited motor.
@@ -129,18 +147,29 @@ reserve storage; `readContactEvents()` reports dropped events or a full pair
 table. End events do not retain an old position. Callbacks run asynchronously.
 
 `sleeping: true` or `{ speedThreshold: 0.03, timeThreshold: 0.5 }` enables an
-optional GPU policy. Supported quiet bodies sleep; impacts, moving joint
-endpoints and explicit edits wake the world conservatively. Unsupported bodies
+optional GPU policy. Supported quiet bodies sleep. Large jointless desktop 3D worlds
+automatically wake conservative connected groups on impact, keeping unrelated
+piles asleep; the shared static floor does not join them. `islands:true` opts
+into group waking in smaller worlds, and `islands:false` selects whole-world
+waking. Explicit edits wake the world and reset group history. Unsupported bodies
 under gravity stay awake. `wakeAll()`, `body.wakeUp()` and `readSleepStats()` are
 available. Suspended jointed objects are not guaranteed to sleep. Defaults and
 paper-comparison benchmarks keep sleeping disabled.
 
+Closed jointless 3D worlds with at most 32 bodies automatically batch movement
+iterations in one GPU workgroup. Body poses stay in shared memory, with the
+same contact order, reductions and equations. Adding a joint or exceeding the
+body limit selects the ordinary pipeline. Qualified mobile compatibility paths
+retain their existing execution policy. `smallGroups:false` disables batching
+for controlled comparisons.
+
 `body.setLinearVelocity()`, `setAngularVelocity()`, `applyImpulse()`,
 `applyAngularImpulse()` and `teleport(position, quaternion)` enqueue compact
 GPU commands. Commands for the same body are combined before submission;
 impulses use the current GPU mass, inertia and position. They never replace a
 body with a stale CPU pose. `teleport` retains velocity unless a velocity setter
-is also called. New aggregates can be added within reserved capacity after
+is also called. Omitting its quaternion preserves the live GPU rotation and
+places the mesh origin at the requested position. New aggregates can be added within reserved capacity after
 initialization; disposed body slots are not reused. For repeated spawning,
 reserve projectile bodies and teleport them. `applyForce()` and `applyTorque()`
 apply forces for one fixed step, using impulses on live GPU state.