avbd-babylon 0.1.0 → 0.3.0

package/dist/gpuDevice.d.ts

@@ -1,6 +1,10 @@
 export function createWebGPUDevice(options?: {
+  /** Run the cached 3D floor-contact qualification and select a working GPU path. */
+  validate3D?: boolean;
   powerPreference?: GPUPowerPreference;
   requiredLimits?: Record<string, number>;
   /** Desired maximum capacities, clamped to the adapter. Required limits take precedence. */
   preferredLimits?: Record<string, number>;
 }): Promise<{ adapter: GPUAdapter; device: GPUDevice }>;
+/** Prepare an existing renderer-owned device for 3D. Does not take device ownership. */
+export function prepareWebGPUDevice3D(device: GPUDevice): Promise<GPUDevice>;

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 } from "./avbd.js";
+export { AvbdScene2D, AvbdScene3D, createWebGPUDevice, prepareWebGPUDevice3D, createSolverPipeline } from "./avbd.js";

package/dist/nativeScenes.d.ts

@@ -1,3 +1,4 @@
+import type { AvbdSolverPipeline, AvbdSolver2D, AvbdSolver3D } from "./solverPipeline.js";
 export type AvbdTuple3 = readonly [number, number, number];
 export type AvbdTuple2 = readonly [number, number];
 export interface AvbdQueryOptions {
@@ -620,6 +621,7 @@ export class AvbdScene3D {
     },
   ): AvbdNativeConstraint;
   createSolver(device: GPUDevice, options?: AvbdGpuOptions): AvbdGpuSolver3D;
+  createSolver(pipeline: AvbdSolverPipeline, options?: AvbdGpuOptions): AvbdSolver3D;
 }
 export interface AvbdNativeAngularOptions {
   axisA?: AvbdTuple3;
@@ -732,4 +734,5 @@ export class AvbdScene2D {
       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/docs/BABYLON_API.md

@@ -16,6 +16,14 @@ last argument when their mesh belongs to the world’s scene. Both `AvbdShapeTyp
 and the supported Babylon `PhysicsShapeType` enum values work. Pass
 `autoAttach: false` when you manage stepping yourself.
 
+`AvbdPhysics.create()` checks 3D floor contacts once per device and automatically
+selects a working GPU path. This covers Android drivers that need compatible
+contact calculations or smaller hull workgroups. Desktop devices that pass
+retain their normal shaders and dispatches. The check adds no per-step readbacks.
+For native 3D solvers, use `createWebGPUDevice({validate3D:true})`, or await
+`prepareWebGPUDevice3D(device)` before using a renderer-owned device. Preparation
+is cached and preserves device ownership. 2D does not require the 3D check.
+
 ```js
 import { Vector3 } from "@babylonjs/core/Maths/math.vector.js";
 import { AvbdPhysics, AvbdPhysicsAggregate, AvbdShapeType } from "avbd-babylon";