avbd-babylon 0.4.4 → 0.4.5

package/dist/babylonAvbd.d.ts

@@ -1,314 +1,347 @@
-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";
-  CAPSULE: "capsule";
-  CYLINDER: "cylinder";
-  CONVEX_HULL: "convex-hull";
-}>;
-export type AvbdShape = (typeof AvbdShapeType)[keyof typeof AvbdShapeType];
-export type AvbdSolverMode = "auto" | "standard" | "optimized" | "points";
-export interface AvbdSolverDecision {
-  requested: AvbdSolverMode;
-  selected: Exclude<AvbdSolverMode, "auto"> | "custom";
-  reason: string;
-  bodyCount: number;
-  constraintCount: number;
-}
-export interface AvbdWorldOptions {
-  device?: GPUDevice;
-  scene?: Scene;
-  gravity?: Vector3 | readonly [number, number, number];
-  /** Attach fixed-step simulation and disposal to the scene. Defaults to true. */
-  autoAttach?: boolean;
-  timeStep?: number;
-  iterations?: number;
-  capacity?: number;
-  syncMeshes?: boolean;
-  maxSyncedBodies?: number;
-  broadphase?: "auto" | "grid" | "hploc";
-  solverMode?: AvbdSolverMode;
-  /** Automatically batch a closed jointless world of up to 32 bodies. */
-  smallGroups?: boolean;
-  /** Advanced: reserve 0–64 parallel solve groups for dense or waking contacts. */
-  minimumColors?: number;
-  /** Advanced: minimum coloring rounds, an even integer from 0–32. */
-  minimumColorRounds?: number;
-  bvh?: { rebuildInterval?: number };
-  /** Optional GPU sleeping. Large worlds wake conservative connected groups on impact. */
-  sleeping?: boolean | AvbdSleepOptions;
-  maxContactPairs?: number;
-  maxContactEvents?: number;
-}
-export interface AvbdAggregateOptions {
-  mass?: number;
-  friction?: number;
-  /** Bounce coefficient 0..1; pair uses the larger coefficient. Defaults to 0. */
-  restitution?: number;
-  /** Defaults to true when world sleeping is enabled. Explicit true enables sleeping. */
-  allowSleep?: boolean;
-  isTrigger?: boolean;
-  sync?: boolean;
-  group?: number;
-  collidesWith?: number;
-}
-export type AvbdVector = Vector3 | readonly [number, number, number];
-export interface AvbdConstraintOptions {
-  type?: "ball" | "fixed" | "spring" | "motor" | "limit";
-  axisA?: AvbdVector;
-  axisB?: AvbdVector;
-  speed?: number;
-  maxTorque?: number;
-  minAngle?: number;
-  maxAngle?: number;
-  anchorA?: AvbdVector;
-  anchorB?: AvbdVector;
-  stiffness?: number;
-  angularStiffness?: number;
-  /** Spring tension in newtons; joints use the angular/optional linear break test. */
-  breakForce?: number;
-  /** Springs only: 0.75 permits 75% tensile extension before breaking. */
-  breakStrain?: number;
-  breakOnPull?: boolean;
-  rest?: number;
-}
-export interface AvbdContactEvent {
-  isTrigger: boolean;
-  type: "begin" | "end";
-  a: AvbdPhysicsBody;
-  b: AvbdPhysicsBody;
-  step: number;
-  point: [number, number, number];
-  normal: [number, number, number];
-  impulse: number;
-}
-export interface AvbdRaycastOptions {
-  includeTriggers?: boolean;
-  maxDistance?: number;
-  ignore?: AvbdPhysicsBody[];
-  collidesWith?: number;
-}
-export interface AvbdRayHit {
-  body: AvbdPhysicsBody | null;
-  index: number;
-  distance: number;
-  point: [number, number, number];
-  normal: [number, number, number];
-}
-export interface AvbdSphereCastHit extends AvbdRayHit {
-  center: [number, number, number];
-}
-export class AvbdPhysicsConstraint {
-  constructor(
-    world: AvbdPhysics,
-    a: AvbdPhysicsBody | null,
-    b: AvbdPhysicsBody,
-    options?: AvbdConstraintOptions,
-  );
-  readonly type: "ball" | "fixed" | "spring" | "motor" | "limit";
-  readonly bodyA: AvbdPhysicsBody | null;
-  readonly bodyB: AvbdPhysicsBody;
-  readonly disposed: boolean;
-  setWorldAnchor(point: AvbdVector): this;
-  setMotor(options: { speed?: number; maxTorque?: number }): this;
-  readState(): Promise<{
-    broken: boolean;
-    linearForce: number[];
-    angularForce: number[];
-  }>;
-  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,
-    direction: AvbdVector,
-    options?: AvbdRaycastOptions,
-  ): Promise<AvbdSphereCastHit | null>;
-  sphereCastAll(
-    casts: Array<{
-      origin: AvbdVector;
-      radius: number;
-      direction: AvbdVector;
-      maxDistance?: number;
-    }>,
-    options?: AvbdRaycastOptions,
-  ): Promise<Array<AvbdSphereCastHit | null>>;
-  addMotor(
-    a: AvbdPhysicsBody | null,
-    b: AvbdPhysicsBody,
-    options?: AvbdConstraintOptions,
-  ): AvbdPhysicsConstraint;
-  addHinge(
-    a: AvbdPhysicsBody | null,
-    b: AvbdPhysicsBody,
-    options?: AvbdHingeOptions,
-  ): AvbdPhysicsHinge;
-  static create(options?: AvbdWorldOptions): Promise<AvbdPhysics>;
-  readonly device: GPUDevice;
-  readonly bodyBuffer: GPUBuffer;
-  readonly steps: number;
-  readonly errors: string[];
-  /** Unexpected device loss stops the scene loop and releases the world. Create a new world/device to resume. */
-  readonly deviceLost: { reason: string; message: string } | null;
-  readonly solverDecision: AvbdSolverDecision;
-  setSolverMode(mode: AvbdSolverMode): AvbdSolverDecision;
-  setGravity(gravity: AvbdVector): void;
-  enableSleeping(options?: AvbdSleepOptions): this;
-  /** Wake all sleeping bodies and disable automatic sleeping. */
-  disableSleeping(): this;
-  initialize(): void;
-  step(): void;
-  flushCommands(): void;
-  addAggregate(
-    mesh: AbstractMesh,
-    type: AvbdShape | PhysicsShapeType,
-    options?: AvbdAggregateOptions,
-  ): AvbdPhysicsAggregate;
-  addAggregates(
-    entries: Array<{
-      mesh: AbstractMesh;
-      type: AvbdShape | PhysicsShapeType;
-      options?: AvbdAggregateOptions;
-    }>,
-  ): AvbdPhysicsAggregate[];
-  attachToScene(scene?: Scene): this;
-  addConstraint(
-    a: AvbdPhysicsBody | null,
-    b: AvbdPhysicsBody,
-    options?: AvbdConstraintOptions,
-  ): AvbdPhysicsConstraint;
-  addJoint(
-    a: AvbdPhysicsBody | null,
-    b: AvbdPhysicsBody,
-    options?: AvbdConstraintOptions,
-  ): AvbdPhysicsConstraint;
-  addWeld(
-    a: AvbdPhysicsBody | null,
-    b: AvbdPhysicsBody,
-    options?: AvbdConstraintOptions,
-  ): AvbdPhysicsConstraint;
-  addSpring(
-    a: AvbdPhysicsBody,
-    b: AvbdPhysicsBody,
-    options?: AvbdConstraintOptions,
-  ): AvbdPhysicsConstraint;
-  onContact(callback: (event: AvbdContactEvent) => void): () => void;
-  readContactEvents(): Promise<{
-    events: AvbdContactEvent[];
-    dropped: number;
-    full: boolean;
-  }>;
-  raycast(
-    origin: AvbdVector,
-    direction: AvbdVector,
-    options?: AvbdRaycastOptions,
-  ): Promise<AvbdRayHit | null>;
-  raycastAll(
-    rays: Array<{
-      origin: AvbdVector;
-      direction: AvbdVector;
-      maxDistance?: number;
-    }>,
-    options?: AvbdRaycastOptions,
-  ): Promise<Array<AvbdRayHit | null>>;
-  getRenderBinding(device?: GPUDevice): {
-    device: GPUDevice;
-    buffer: GPUBuffer;
-    stride: number;
-    positionOffset: number;
-    rotationOffset: number;
-    sizeOffset: number;
-    count: number;
-  };
-  wakeAll(): void;
-  readSleepStats(): Promise<{ sleeping: number; wakeRequested: boolean }>;
-  readonly lastSyncBytes: number | undefined;
-  syncMeshes(): Promise<void>;
-  /** With bodies: requested order, 40 floats each. Without: GPU slot order. */
-  readBodies(bodies?: AvbdPhysicsBody[]): Promise<Float32Array>;
-  dispose(): void;
-}
-export interface AvbdHingeOptions extends AvbdConstraintOptions {
-  span?: number;
-  motor?: { speed?: number; maxTorque?: number };
-}
-export class AvbdPhysicsHinge {
-  constructor(
-    world: AvbdPhysics,
-    a: AvbdPhysicsBody | null,
-    b: AvbdPhysicsBody,
-    options?: AvbdHingeOptions,
-  );
-  readonly bodyA: AvbdPhysicsBody | null;
-  readonly bodyB: AvbdPhysicsBody;
-  readonly joints: AvbdPhysicsConstraint[];
-  readonly limit?: AvbdPhysicsConstraint;
-  readonly motor?: AvbdPhysicsConstraint;
-  readonly disposed: boolean;
-  dispose(): void;
-}
-export class AvbdPhysicsAggregate {
-  constructor(
-    mesh: AbstractMesh,
-    type: AvbdShape | PhysicsShapeType,
-    options?: AvbdAggregateOptions,
-    world?: AvbdPhysics | Scene,
-  );
-  readonly mesh: AbstractMesh;
-  readonly body: AvbdPhysicsBody;
-  readonly type: AvbdShape;
-  dispose(): void;
-}
-export class AvbdPhysicsBody {
-  readonly gpuIndex: number;
-  setLinearVelocity(velocity: AvbdVector): this;
-  setAngularVelocity(velocity: AvbdVector): this;
-  applyImpulse(impulse: AvbdVector, worldPoint?: AvbdVector): this;
-  applyAngularImpulse(impulse: AvbdVector): this;
-  /** Apply force for one fixed step (N), optionally at a world point. */
-  applyForce(force: AvbdVector, worldPoint?: AvbdVector): this;
-  applyTorque(torque: AvbdVector): this;
-  setCollisionGroups(group: number, collidesWith?: number): this;
-  wakeUp(): this;
-  setSleepEnabled(enabled: boolean): this;
-  setTrigger(enabled: boolean): this;
-  setRestitution(value: number): this;
-  readState(): Promise<{
-    position: number[];
-    rotation: number[];
-    linearVelocity: number[];
-    angularVelocity: number[];
-    mass: number;
-    effectiveMass: number;
-    sleeping: boolean;
-  }>;
-  /** Mesh-origin position; preserves live rotation and velocities when omitted. */
-  teleport(position: Vector3, rotation?: Quaternion): this;
-}
+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";
+  CAPSULE: "capsule";
+  CYLINDER: "cylinder";
+  CONVEX_HULL: "convex-hull";
+}>;
+export type AvbdShape = (typeof AvbdShapeType)[keyof typeof AvbdShapeType];
+export type AvbdSolverMode = "auto" | "standard" | "optimized" | "points";
+export interface AvbdSolverDecision {
+  requested: AvbdSolverMode;
+  selected: Exclude<AvbdSolverMode, "auto"> | "custom";
+  reason: string;
+  bodyCount: number;
+  constraintCount: number;
+}
+/**
+ * GPU world setup. Build aggregates before initialization and reserve enough
+ * capacity for later additions. A supplied GPUDevice remains caller-owned.
+ */
+export interface AvbdWorldOptions {
+  device?: GPUDevice;
+  scene?: Scene;
+  gravity?: Vector3 | readonly [number, number, number];
+  /** Attach fixed-step simulation and disposal to the scene. Defaults to true. */
+  autoAttach?: boolean;
+  timeStep?: number;
+  iterations?: number;
+  /** Maximum body slots reserved at initialization; default 4096. */
+  capacity?: number;
+  /** Mirror selected poses for ordinary Babylon meshes. Use false with direct GPU drawing. */
+  syncMeshes?: boolean;
+  /** Guard against accidental large pose downloads; default 2048. */
+  maxSyncedBodies?: number;
+  broadphase?: "auto" | "grid" | "hploc";
+  solverMode?: AvbdSolverMode;
+  /** Automatically batch a closed jointless world of up to 32 bodies. */
+  smallGroups?: boolean;
+  /** Advanced: reserve 0–64 parallel solve groups for dense or waking contacts. */
+  minimumColors?: number;
+  /** Advanced: minimum coloring rounds, an even integer from 0–32. */
+  minimumColorRounds?: number;
+  bvh?: { rebuildInterval?: number };
+  /** Optional GPU sleeping. Large worlds wake conservative connected groups on impact. */
+  sleeping?: boolean | AvbdSleepOptions;
+  maxContactPairs?: number;
+  maxContactEvents?: number;
+}
+export interface AvbdAggregateOptions {
+  mass?: number;
+  friction?: number;
+  /** Bounce coefficient 0..1; pair uses the larger coefficient. Defaults to 0. */
+  restitution?: number;
+  /** Defaults to true when world sleeping is enabled. Explicit true enables sleeping. */
+  allowSleep?: boolean;
+  /** Overlap sensor: contact events without physical contact response. */
+  isTrigger?: boolean;
+  /** Include this aggregate in pose mirroring when world syncMeshes is enabled. */
+  sync?: boolean;
+  group?: number;
+  collidesWith?: number;
+}
+export type AvbdVector = Vector3 | readonly [number, number, number];
+export interface AvbdConstraintOptions {
+  type?: "ball" | "fixed" | "spring" | "motor" | "limit";
+  axisA?: AvbdVector;
+  axisB?: AvbdVector;
+  /** Motor target angular speed in radians/second. */
+  speed?: number;
+  maxTorque?: number;
+  /** Lower relative hinge angle in radians. */
+  minAngle?: number;
+  /** Upper relative hinge angle in radians. */
+  maxAngle?: number;
+  /** Mesh-local anchor, or world-space when body A is null. */
+  anchorA?: AvbdVector;
+  /** Anchor in body B's mesh-local coordinates. */
+  anchorB?: AvbdVector;
+  stiffness?: number;
+  angularStiffness?: number;
+  /** Spring tension in newtons; joints use the angular/optional linear break test. */
+  breakForce?: number;
+  /** Springs only: 0.75 permits 75% tensile extension before breaking. */
+  breakStrain?: number;
+  breakOnPull?: boolean;
+  rest?: number;
+}
+export interface AvbdContactEvent {
+  isTrigger: boolean;
+  type: "begin" | "end";
+  a: AvbdPhysicsBody;
+  b: AvbdPhysicsBody;
+  step: number;
+  point: [number, number, number];
+  normal: [number, number, number];
+  impulse: number;
+}
+export interface AvbdRaycastOptions {
+  includeTriggers?: boolean;
+  maxDistance?: number;
+  ignore?: AvbdPhysicsBody[];
+  collidesWith?: number;
+}
+export interface AvbdRayHit {
+  body: AvbdPhysicsBody | null;
+  index: number;
+  distance: number;
+  point: [number, number, number];
+  normal: [number, number, number];
+}
+export interface AvbdSphereCastHit extends AvbdRayHit {
+  center: [number, number, number];
+}
+export class AvbdPhysicsConstraint {
+  constructor(
+    world: AvbdPhysics,
+    a: AvbdPhysicsBody | null,
+    b: AvbdPhysicsBody,
+    options?: AvbdConstraintOptions,
+  );
+  readonly type: "ball" | "fixed" | "spring" | "motor" | "limit";
+  readonly bodyA: AvbdPhysicsBody | null;
+  readonly bodyB: AvbdPhysicsBody;
+  readonly disposed: boolean;
+  setWorldAnchor(point: AvbdVector): this;
+  setMotor(options: { speed?: number; maxTorque?: number }): this;
+  readState(): Promise<{
+    broken: boolean;
+    linearForce: number[];
+    angularForce: number[];
+  }>;
+  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,
+    direction: AvbdVector,
+    options?: AvbdRaycastOptions,
+  ): Promise<AvbdSphereCastHit | null>;
+  /** Batch swept-sphere queries; one nearest hit or null per input cast. */
+  sphereCastAll(
+    casts: Array<{
+      origin: AvbdVector;
+      radius: number;
+      direction: AvbdVector;
+      maxDistance?: number;
+    }>,
+    options?: AvbdRaycastOptions,
+  ): Promise<Array<AvbdSphereCastHit | null>>;
+  addMotor(
+    a: AvbdPhysicsBody | null,
+    b: AvbdPhysicsBody,
+    options?: AvbdConstraintOptions,
+  ): AvbdPhysicsConstraint;
+  addHinge(
+    a: AvbdPhysicsBody | null,
+    b: AvbdPhysicsBody,
+    options?: AvbdHingeOptions,
+  ): AvbdPhysicsHinge;
+  /** Create the GPU world; attaches to a supplied Babylon scene by default. */
+  static create(options?: AvbdWorldOptions): Promise<AvbdPhysics>;
+  readonly device: GPUDevice;
+  readonly bodyBuffer: GPUBuffer;
+  readonly steps: number;
+  readonly errors: string[];
+  /** Unexpected device loss stops the scene loop and releases the world. Create a new world/device to resume. */
+  readonly deviceLost: { reason: string; message: string } | null;
+  readonly solverDecision: AvbdSolverDecision;
+  setSolverMode(mode: AvbdSolverMode): AvbdSolverDecision;
+  setGravity(gravity: AvbdVector): void;
+  enableSleeping(options?: AvbdSleepOptions): this;
+  /** Wake all sleeping bodies and disable automatic sleeping. */
+  disableSleeping(): this;
+  /** Upload initial topology once; step(), queries and buffer access initialize lazily. */
+  initialize(): void;
+  /** Submit one fixed step; do not also call manually when automatic scene stepping is attached. */
+  step(): void;
+  /** Apply queued edits without stepping or waiting. step() also flushes them automatically. */
+  flushCommands(): void;
+  addAggregate(
+    mesh: AbstractMesh,
+    type: AvbdShape | PhysicsShapeType,
+    options?: AvbdAggregateOptions,
+  ): AvbdPhysicsAggregate;
+  /** Convenience construction of multiple aggregates; each retains its own body. */
+  addAggregates(
+    entries: Array<{
+      mesh: AbstractMesh;
+      type: AvbdShape | PhysicsShapeType;
+      options?: AvbdAggregateOptions;
+    }>,
+  ): AvbdPhysicsAggregate[];
+  /** Attach fixed-step updates and disposal to the scene; reuse the same scene idempotently. */
+  attachToScene(scene?: Scene): this;
+  addConstraint(
+    a: AvbdPhysicsBody | null,
+    b: AvbdPhysicsBody,
+    options?: AvbdConstraintOptions,
+  ): AvbdPhysicsConstraint;
+  addJoint(
+    a: AvbdPhysicsBody | null,
+    b: AvbdPhysicsBody,
+    options?: AvbdConstraintOptions,
+  ): AvbdPhysicsConstraint;
+  addWeld(
+    a: AvbdPhysicsBody | null,
+    b: AvbdPhysicsBody,
+    options?: AvbdConstraintOptions,
+  ): AvbdPhysicsConstraint;
+  addSpring(
+    a: AvbdPhysicsBody,
+    b: AvbdPhysicsBody,
+    options?: AvbdConstraintOptions,
+  ): AvbdPhysicsConstraint;
+  /** Receive asynchronously downloaded begin/end events; returns an unsubscribe function. */
+  onContact(callback: (event: AvbdContactEvent) => void): () => void;
+  readContactEvents(): Promise<{
+    events: AvbdContactEvent[];
+    dropped: number;
+    full: boolean;
+  }>;
+  raycast(
+    origin: AvbdVector,
+    direction: AvbdVector,
+    options?: AvbdRaycastOptions,
+  ): Promise<AvbdRayHit | null>;
+  /** Batch rays in one query; returns the nearest hit or null for each input, in input order. */
+  raycastAll(
+    rays: Array<{
+      origin: AvbdVector;
+      direction: AvbdVector;
+      maxDistance?: number;
+    }>,
+    options?: AvbdRaycastOptions,
+  ): Promise<Array<AvbdRayHit | null>>;
+  /**
+   * Borrow live poses on the same GPUDevice. Stride and offsets are bytes.
+   * The world owns this buffer; it is invalid after disposal.
+   */
+  getRenderBinding(device?: GPUDevice): {
+    device: GPUDevice;
+    buffer: GPUBuffer;
+    stride: number;
+    positionOffset: number;
+    rotationOffset: number;
+    sizeOffset: number;
+    count: number;
+  };
+  wakeAll(): void;
+  readSleepStats(): Promise<{ sleeping: number; wakeRequested: boolean }>;
+  readonly lastSyncBytes: number | undefined;
+  /** Explicitly mirror only sync-enabled aggregate poses; asynchronous GPU readback. */
+  syncMeshes(): Promise<void>;
+  /** With bodies: requested order, 40 floats each. Without: GPU slot order. */
+  readBodies(bodies?: AvbdPhysicsBody[]): Promise<Float32Array>;
+  dispose(): void;
+}
+export interface AvbdHingeOptions extends AvbdConstraintOptions {
+  span?: number;
+  motor?: { speed?: number; maxTorque?: number };
+}
+export class AvbdPhysicsHinge {
+  constructor(
+    world: AvbdPhysics,
+    a: AvbdPhysicsBody | null,
+    b: AvbdPhysicsBody,
+    options?: AvbdHingeOptions,
+  );
+  readonly bodyA: AvbdPhysicsBody | null;
+  readonly bodyB: AvbdPhysicsBody;
+  readonly joints: AvbdPhysicsConstraint[];
+  readonly limit?: AvbdPhysicsConstraint;
+  readonly motor?: AvbdPhysicsConstraint;
+  readonly disposed: boolean;
+  dispose(): void;
+}
+export class AvbdPhysicsAggregate {
+  constructor(
+    mesh: AbstractMesh,
+    type: AvbdShape | PhysicsShapeType,
+    options?: AvbdAggregateOptions,
+    world?: AvbdPhysics | Scene,
+  );
+  readonly mesh: AbstractMesh;
+  readonly body: AvbdPhysicsBody;
+  readonly type: AvbdShape;
+  dispose(): void;
+}
+export class AvbdPhysicsBody {
+  readonly gpuIndex: number;
+  /** Queue world-space velocity replacement; repeated calls before flush keep the last value. */
+  setLinearVelocity(velocity: AvbdVector): this;
+  setAngularVelocity(velocity: AvbdVector): this;
+  /** Queue an additive world-space impulse; optional worldPoint also applies torque. */
+  applyImpulse(impulse: AvbdVector, worldPoint?: AvbdVector): this;
+  applyAngularImpulse(impulse: AvbdVector): this;
+  /** Apply force for one fixed step (N), optionally at a world point. */
+  applyForce(force: AvbdVector, worldPoint?: AvbdVector): this;
+  applyTorque(torque: AvbdVector): this;
+  /** Unsigned bitmasks; both bodies must accept the other's group to interact. */
+  setCollisionGroups(group: number, collidesWith?: number): this;
+  wakeUp(): this;
+  /** Opt this body into/out of resting detection; true enables world sleeping if needed. */
+  setSleepEnabled(enabled: boolean): this;
+  setTrigger(enabled: boolean): this;
+  /** Bounce coefficient in [0, 1]. Zero retains ordinary solid contact response. */
+  setRestitution(value: number): this;
+  readState(): Promise<{
+    position: number[];
+    rotation: number[];
+    linearVelocity: number[];
+    angularVelocity: number[];
+    mass: number;
+    effectiveMass: number;
+    sleeping: boolean;
+  }>;
+  /** Mesh-origin position; preserves live rotation and velocities when omitted. */
+  teleport(position: Vector3, rotation?: Quaternion): this;
+}