angular-three-cannon 4.0.0-next.98 → 4.0.0

package/README.md

@@ -2,6 +2,10 @@
 
 This library is a wrapper around the [Cannon.js](https://schteppe.github.io/cannon.js/) physics engine for use with Angular Three.
 
+## Documentation
+
+All public APIs are documented with JSDoc comments. Your IDE will provide inline documentation, parameter hints, and examples as you code.
+
 ## Installation
 
 ```bash
@@ -15,6 +19,11 @@ npm install angular-three-cannon cannon-es @pmndrs/cannon-worker-api
 ## Usage
 
 ```typescript
+import { Component, viewChild, ElementRef } from '@angular/core';
+import { Mesh } from 'three';
+import { NgtcPhysics } from 'angular-three-cannon';
+import { box } from 'angular-three-cannon/body';
+
 @Component({
 	template: `
 		<ngt-mesh #mesh>
@@ -27,7 +36,7 @@ export class Box {
 
 	constructor() {
 		// Make this mesh a Box body in Physics. Only works within ngtc-physics
-		injectBox(() => ({ mass: 10000, position: [0, 0, 0], args: [1, 1, 1] }), this.mesh);
+		box(() => ({ mass: 10000, position: [0, 0, 0], args: [1, 1, 1] }), this.mesh);
 	}
 }
 
@@ -42,24 +51,34 @@ export class Box {
 export class SceneGraph {}
 ```
 
-### Inputs
-
-- `allowSleep?: boolean`
-- `axisIndex?: 0 | 1 | 2`
-- `broadphase?: 'Naive' | 'SAP'`
-- `defaultContactMaterial?: ContactMaterialOptions`
-- `frictionGravity?: Vector3 | null`
-- `gravity?: Vector3`
-- `isPaused?: boolean`
-- `iterations?: number`
-- `maxSubSteps?: number`
-- `quatNormalizeFast?: boolean`
-- `quatNormalizeSkip?: number`
-- `shouldInvalidate?: boolean`
-- `size?: number`
-- `solver?: 'GS' | 'Split'`
-- `stepSize?: number`
-- `tolerance?: number`
+### Options
+
+The `NgtcPhysics` component accepts an `options` input with the following properties:
+
+```html
+<ngtc-physics [options]="{ gravity: [0, -9.81, 0], iterations: 10 }">
+	<!-- Physics bodies here -->
+</ngtc-physics>
+```
+
+| Property                 | Type                     | Default                             |
+| ------------------------ | ------------------------ | ----------------------------------- |
+| `allowSleep`             | `boolean`                | `false`                             |
+| `axisIndex`              | `0 \| 1 \| 2`            | `0`                                 |
+| `broadphase`             | `'Naive' \| 'SAP'`       | `'Naive'`                           |
+| `defaultContactMaterial` | `ContactMaterialOptions` | `{ contactEquationStiffness: 1e6 }` |
+| `frictionGravity`        | `Vector3 \| null`        | `null`                              |
+| `gravity`                | `Vector3`                | `[0, -9.81, 0]`                     |
+| `isPaused`               | `boolean`                | `false`                             |
+| `iterations`             | `number`                 | `5`                                 |
+| `maxSubSteps`            | `number`                 | `10`                                |
+| `quatNormalizeFast`      | `boolean`                | `false`                             |
+| `quatNormalizeSkip`      | `number`                 | `0`                                 |
+| `shouldInvalidate`       | `boolean`                | `true`                              |
+| `size`                   | `number`                 | `1000`                              |
+| `solver`                 | `'GS' \| 'Split'`        | `'GS'`                              |
+| `stepSize`               | `number`                 | `1/60`                              |
+| `tolerance`              | `number`                 | `0.001`                             |
 
 ## Debug
 

package/body/README.md

@@ -1,26 +1,31 @@
 # `angular-three-cannon/body`
 
-This module provides a set of custom injector functions to create physics bodies that link `ngt-*` objects in THREE.js with bodies in the Cannon.js physics world. These functions simplify the process of adding physics behavior to your 3D objects.
-
-### Available `inject*` Functions
-
-| Function                 | Description                                      | `getProps` Arguments                                                     | `object` Type |
-| :----------------------- | :----------------------------------------------- | :----------------------------------------------------------------------- | :------------ |
-| `injectBox`              | Creates a box-shaped physics body.               | `mass`, `position`, `args: [width, height, depth]`                       | `ElementRef`  |
-| `injectConvexPolyhedron` | Creates a convex polyhedron-shaped physics body. | `mass`, `position`, `vertices`, `faces`                                  | `ElementRef`  |
-| `injectCylinder`         | Creates a cylinder-shaped physics body.          | `mass`, `position`, `radiusTop`, `radiusBottom`, `height`, `numSegments` | `ElementRef`  |
-| `injectHeightfield`      | Creates a heightfield-shaped physics body.       | `mass`, `position`, `data`, `elementSize`                                | `ElementRef`  |
-| `injectParticle`         | Creates a particle physics body.                 | `mass`, `position`                                                       | `ElementRef`  |
-| `injectPlane`            | Creates a plane-shaped physics body.             | `mass`, `position`                                                       | `ElementRef`  |
-| `injectSphere`           | Creates a sphere-shaped physics body.            | `mass`, `position`, `radius`                                             | `ElementRef`  |
-| `injectTrimesh`          | Creates a trimesh-shaped physics body.           | `mass`, `position`, `vertices`, `indices`                                | `ElementRef`  |
-| `injectCompound`         | Creates a compound physics body.                 | `mass`, `position`, `shapes`                                             | `ElementRef`  |
+This module provides functions to create physics bodies that link `ngt-*` objects in THREE.js with bodies in the Cannon.js physics world. These functions simplify the process of adding physics behavior to your 3D objects.
+
+### Available Body Functions
+
+| Function           | Description                                      | `args` Arguments                                 | `object` Type |
+| :----------------- | :----------------------------------------------- | :----------------------------------------------- | :------------ |
+| `box`              | Creates a box-shaped physics body.               | `[width, height, depth]`                         | `ElementRef`  |
+| `convexPolyhedron` | Creates a convex polyhedron-shaped physics body. | `[vertices, faces]`                              | `ElementRef`  |
+| `cylinder`         | Creates a cylinder-shaped physics body.          | `[radiusTop, radiusBottom, height, numSegments]` | `ElementRef`  |
+| `heightfield`      | Creates a heightfield-shaped physics body.       | `[data, { elementSize }]`                        | `ElementRef`  |
+| `particle`         | Creates a particle physics body.                 | (none)                                           | `ElementRef`  |
+| `plane`            | Creates a plane-shaped physics body.             | (none)                                           | `ElementRef`  |
+| `sphere`           | Creates a sphere-shaped physics body.            | `[radius]`                                       | `ElementRef`  |
+| `trimesh`          | Creates a trimesh-shaped physics body.           | `[vertices, indices]`                            | `ElementRef`  |
+| `compound`         | Creates a compound physics body.                 | (uses `shapes` property instead)                 | `ElementRef`  |
 
 **All functions also accept an optional `options` argument for additional customization.**
 
-### Simple Usage of `injectBox()`
+### Simple Usage of `box()`
 
 ```typescript
+import { Component, viewChild, ElementRef } from '@angular/core';
+import { Mesh } from 'three';
+import { NgtcPhysics } from 'angular-three-cannon';
+import { box } from 'angular-three-cannon/body';
+
 @Component({
 	template: `
 		<ngt-mesh #mesh>
@@ -33,7 +38,7 @@ export class Box {
 
 	constructor() {
 		// Make this mesh a Box body in Physics. Only works within ngtc-physics
-		injectBox(() => ({ mass: 10000, position: [0, 0, 0], args: [1, 1, 1] }), this.mesh);
+		box(() => ({ mass: 10000, position: [0, 0, 0], args: [1, 1, 1] }), this.mesh);
 	}
 }
 
@@ -47,3 +52,19 @@ export class Box {
 })
 export class SceneGraph {}
 ```
+
+### Deprecated Functions
+
+The following `inject*` functions are deprecated and will be removed in v5.0.0. Use the new function names instead:
+
+| Deprecated               | Use Instead        |
+| :----------------------- | :----------------- |
+| `injectBox`              | `box`              |
+| `injectConvexPolyhedron` | `convexPolyhedron` |
+| `injectCylinder`         | `cylinder`         |
+| `injectHeightfield`      | `heightfield`      |
+| `injectParticle`         | `particle`         |
+| `injectPlane`            | `plane`            |
+| `injectSphere`           | `sphere`           |
+| `injectTrimesh`          | `trimesh`          |
+| `injectCompound`         | `compound`         |

package/constraint/README.md

@@ -2,22 +2,23 @@
 
 This module provides functions to create physics constraints that link physics bodies in the Cannon.js physics world. These functions simplify the process of adding constraints between your 3D objects.
 
-### Available constraint functions
+### Available Constraint Functions
 
-| Function       | Description                                                                                                                                                  | Arguments                        |
-| :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------- |
-| `pointToPoint` | Creates a point-to-point constraint between two bodies. The constraint tries to keep the distance between the anchor points constant.                        | `objectA`, `objectB`, `getProps` |
-| `coneTwist`    | Creates a cone-twist constraint between two bodies. The constraint attempts to keep the bodies aligned along a common axis, allowing swing and twist motion. | `objectA`, `objectB`, `getProps` |
-| `distance`     | Creates a distance constraint between two bodies. The constraint tries to keep the distance between the bodies' center of masses constant.                   | `objectA`, `objectB`, `getProps` |
-| `lock`         | Creates a lock constraint between two bodies. The constraint completely locks the motion of one body relative to another.                                    | `objectA`, `objectB`, `getProps` |
-| `hinge`        | Creates a hinge constraint between two bodies. The constraint allows for rotation around a shared axis, like a door hinge.                                   | `objectA`, `objectB`, `getProps` |
+| Function       | Description                                                                                                                                                  |
+| :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pointToPoint` | Creates a point-to-point constraint between two bodies. The constraint tries to keep the distance between the anchor points constant.                        |
+| `coneTwist`    | Creates a cone-twist constraint between two bodies. The constraint attempts to keep the bodies aligned along a common axis, allowing swing and twist motion. |
+| `distance`     | Creates a distance constraint between two bodies. The constraint tries to keep the distance between the bodies' center of masses constant.                   |
+| `lock`         | Creates a lock constraint between two bodies. The constraint completely locks the motion of one body relative to another.                                    |
+| `hinge`        | Creates a hinge constraint between two bodies. The constraint allows for rotation around a shared axis, like a door hinge.                                   |
 
-**All functions' `getProps` argument is a function that returns the properties of the constraint.**
+**All functions take `bodyA`, `bodyB`, and an optional `options` object as arguments.**
 
 ### Simple Usage of `hinge()`
 
 ```typescript
 import { Component, viewChild, ElementRef } from '@angular/core';
+import { Mesh } from 'three';
 import { hinge } from 'angular-three-cannon/constraint';
 
 @Component({
@@ -36,12 +37,38 @@ export class HingedBoxes {
 
 	constructor() {
 		// Create a hinge constraint between mesh1 and mesh2. Only works within <ngtc-physics>
-		hinge(this.mesh1, this.mesh2, () => ({
-			pivotA: [0, 0.5, 0], // hinge location on the first body
-			pivotB: [0, -0.5, 0], // hinge location on the second body
-			axisA: [0, 1, 0], // axis of rotation on the first body
-			axisB: [0, 1, 0], // axis of rotation on the second body
-		}));
+		hinge(this.mesh1, this.mesh2, {
+			options: {
+				pivotA: [0, 0.5, 0], // hinge location on the first body
+				pivotB: [0, -0.5, 0], // hinge location on the second body
+				axisA: [0, 1, 0], // axis of rotation on the first body
+				axisB: [0, 1, 0], // axis of rotation on the second body
+			},
+		});
 	}
 }
 ```
+
+### Constraint Options
+
+All constraint functions accept an optional third argument with the following properties:
+
+```typescript
+interface NgtcConstraintOptions {
+	injector?: Injector; // Angular injector for dependency injection
+	disableOnStart?: boolean; // Whether to create the constraint disabled (default: false)
+	options?: ConstraintSpecificOptions; // Constraint-specific configuration
+}
+```
+
+### Deprecated Functions
+
+The following `inject*` functions are deprecated and will be removed in v5.0.0. Use the new function names instead:
+
+| Deprecated           | Use Instead    |
+| :------------------- | :------------- |
+| `injectPointToPoint` | `pointToPoint` |
+| `injectConeTwist`    | `coneTwist`    |
+| `injectDistance`     | `distance`     |
+| `injectLock`         | `lock`         |
+| `injectHinge`        | `hinge`        |

package/debug/README.md

@@ -14,23 +14,11 @@ npm install cannon-es-debugger
 # pnpm add cannon-es-debugger
 ```
 
-## NgtcDebugApi
-
-The `NgtcDebugApi` interface provides methods to interact with the debug renderer:
-
-- `add(uuid: string, props: BodyProps, type: BodyShapeType)`: Adds a physics body to the debug renderer.
-- `remove(uuid: string)`: Removes a physics body from the debug renderer.
-
-### `injectNgtcDebugApi`
-
-The `injectNgtcDebugApi` function is used to inject the `NgtcDebugApi` into your components, enabling you to control the debug visualization.
-
 ## NgtcDebug
 
-The `NgtcDebug` directive is applied to the `ngtc-physics` component to enable physics debugging. It has the following inputs:
+The `NgtcDebug` directive is applied to the `ngtc-physics` component to enable physics debugging. It has the following input:
 
 - `debug`: An object containing the following properties:
-
     - `enabled`: (boolean) Whether the debug visualization is enabled (default: true).
     - `color`: (string) The color of the debug visualization (default: 'black').
     - `impl`: (typeof CannonDebugger) The implementation of the CannonDebugger to use (default: CannonDebugger).
@@ -39,11 +27,32 @@ The `NgtcDebug` directive is applied to the `ngtc-physics` component to enable p
 ## Usage
 
 ```html
-<ngtc-physics debug></ngtc-physics>
+<ngtc-physics [debug]="{ enabled: true }">
+	<!-- Physics bodies here -->
+</ngtc-physics>
 ```
 
 You can customize the debug visualization by providing input values within the `debug` object:
 
 ```html
-<ngtc-physics [debug]="{enabled: true, color: 'red', scale: 0.5}"></ngtc-physics>
+<ngtc-physics [debug]="{ enabled: true, color: 'red', scale: 0.5 }">
+	<!-- Physics bodies here -->
+</ngtc-physics>
+```
+
+Toggle debug visualization based on component state:
+
+```html
+<ngtc-physics [debug]="{ enabled: isDebugging() }">
+	<!-- Physics bodies here -->
+</ngtc-physics>
 ```
+
+## NgtcDebug Methods
+
+The `NgtcDebug` class provides the following methods for internal use:
+
+- `add(uuid: string, props: BodyProps, type: BodyShapeType)`: Adds a physics body to the debug renderer.
+- `remove(uuid: string)`: Removes a physics body from the debug renderer.
+
+These methods are called automatically by body functions when debug is enabled.

package/fesm2022/angular-three-cannon-body.mjs

@@ -20,6 +20,25 @@ function quaternionToRotation(callback) {
     return (v) => callback(e.setFromQuaternion(q.fromArray(v)).toArray());
 }
 let incrementingId = 0;
+/**
+ * Creates a subscription function for monitoring physics body property changes.
+ *
+ * @template T - The subscription property name type
+ * @param body - The Three.js Object3D associated with the physics body
+ * @param worker - The Cannon.js worker API instance
+ * @param subscriptions - Map to store active subscriptions
+ * @param type - The property type to subscribe to (e.g., 'position', 'velocity')
+ * @param index - Optional instance index for InstancedMesh bodies
+ * @param target - Subscription target, defaults to 'bodies'
+ * @returns Function that creates a subscription and returns an unsubscribe function
+ *
+ * @example
+ * ```typescript
+ * const subscribe = createSubscribe(body, worker, subscriptions, 'position');
+ * const unsubscribe = subscribe((position) => console.log(position));
+ * // Later: unsubscribe();
+ * ```
+ */
 function createSubscribe(body, worker, subscriptions, type, index, target = 'bodies') {
     return (callback) => {
         const id = incrementingId++;
@@ -35,15 +54,51 @@ function createSubscribe(body, worker, subscriptions, type, index, target = 'bod
 function makeTriplet(v) {
     return is.three(v, 'isVector3') ? [v.x, v.y, v.z] : v;
 }
+/**
+ * Prepares a Three.js Object3D with initial physics body properties.
+ * Sets the object's position, rotation, and userData from body props.
+ *
+ * @param object - The Three.js Object3D to prepare
+ * @param props - Body properties containing position, rotation, and userData
+ *
+ * @example
+ * ```typescript
+ * prepare(mesh, { position: [0, 5, 0], rotation: [0, Math.PI, 0] });
+ * ```
+ */
 function prepare(object, { position = [0, 0, 0], rotation = [0, 0, 0], userData = {} }) {
     object.userData = userData;
     object.position.set(...position);
     object.rotation.set(...rotation);
     object.updateMatrix();
 }
+/**
+ * Sets up collision event handlers for a physics body.
+ * Registers callbacks for collide, collideBegin, and collideEnd events.
+ *
+ * @param events - The events map to register handlers in
+ * @param props - Body props containing collision callback functions
+ * @param uuid - The unique identifier for the physics body
+ */
 function setupCollision(events, { onCollide, onCollideBegin, onCollideEnd }, uuid) {
     events[uuid] = { collide: onCollide, collideBegin: onCollideBegin, collideEnd: onCollideEnd };
 }
+/**
+ * Creates the public API for controlling a physics body.
+ * Provides methods for applying forces, setting properties, and subscribing to changes.
+ *
+ * @param body - The Three.js Object3D associated with the physics body
+ * @param worker - The Cannon.js worker API instance
+ * @param context - Physics context containing subscriptions and scale overrides
+ * @returns The body's public API with all available methods
+ *
+ * @example
+ * ```typescript
+ * const api = makeBodyApi(mesh, worker, { subscriptions, scaleOverrides });
+ * api.applyForce([0, 100, 0], [0, 0, 0]);
+ * api.position.subscribe((pos) => console.log(pos));
+ * ```
+ */
 function makeBodyApi(body, worker, { subscriptions, scaleOverrides }) {
     const makeAtomic = (type, index) => {
         const op = `set${capitalize(type)}`;
@@ -175,6 +230,21 @@ function makeBodyApi(body, worker, { subscriptions, scaleOverrides }) {
     const cache = {};
     return { ...makeApi(), at: (index) => cache[index] || (cache[index] = makeApi(index)) };
 }
+/**
+ * Default argument transformation functions for each physics body shape type.
+ * These functions convert Three.js-friendly arguments to Cannon.js-compatible formats.
+ *
+ * Each transformer handles the specific requirements of its shape type:
+ * - Plane: No arguments needed
+ * - Box: [width, height, depth], defaults to [1, 1, 1]
+ * - Trimesh: Passes through vertices and indices unchanged
+ * - Cylinder: No arguments needed (uses shape defaults)
+ * - Heightfield: Passes through height data unchanged
+ * - ConvexPolyhedron: Converts Vector3 arrays to triplet arrays
+ * - Particle: No arguments needed
+ * - Sphere: [radius], defaults to [1]
+ * - Compound: Passes through shape array unchanged
+ */
 const defaultTransformArgs = {
     Plane: (_) => [],
     Box: (args = [1, 1, 1]) => args,
@@ -210,7 +280,7 @@ function body(type, getPropFn, ref, { transformArgs, injector } = {}) {
         const transform = transformArgs ?? defaultTransformArgs[type];
         const isRefSignal = isSignal(ref);
         const bodyRef = (isRefSignal ? ref : signal(ref));
-        const body = computed(() => resolveRef(bodyRef()));
+        const body = computed(() => resolveRef(bodyRef()), ...(ngDevMode ? [{ debugName: "body" }] : []));
         const api = computed(() => {
             const _body = body();
             if (!_body)
@@ -220,7 +290,7 @@ function body(type, getPropFn, ref, { transformArgs, injector } = {}) {
             if (!_worker)
                 return null;
             return makeBodyApi(_body, _worker, rest);
-        });
+        }, ...(ngDevMode ? [{ debugName: "api" }] : []));
         effect((onCleanup) => {
             const currentWorker = physics.worker();
             if (!currentWorker)
@@ -288,14 +358,168 @@ function body(type, getPropFn, ref, { transformArgs, injector } = {}) {
         return api;
     });
 }
+/**
+ * Creates a box-shaped physics body.
+ *
+ * @param getPropFn - Function returning body properties for each instance index
+ * @param ref - Reference to the Three.js Object3D to attach physics to
+ * @param options - Optional configuration for the body
+ * @returns Signal containing the body's public API, or null if not ready
+ *
+ * @example
+ * ```typescript
+ * const mesh = viewChild.required<ElementRef<Mesh>>('mesh');
+ * const api = box(() => ({ mass: 1, args: [1, 1, 1], position: [0, 5, 0] }), mesh);
+ * ```
+ */
 const box = createBody('Box');
+/**
+ * Creates a convex polyhedron physics body from vertices and faces.
+ *
+ * @param getPropFn - Function returning body properties for each instance index
+ * @param ref - Reference to the Three.js Object3D to attach physics to
+ * @param options - Optional configuration for the body
+ * @returns Signal containing the body's public API, or null if not ready
+ *
+ * @example
+ * ```typescript
+ * const mesh = viewChild.required<ElementRef<Mesh>>('mesh');
+ * const api = convexPolyhedron(() => ({
+ *   mass: 1,
+ *   args: [vertices, faces],
+ *   position: [0, 5, 0]
+ * }), mesh);
+ * ```
+ */
 const convexPolyhedron = createBody('ConvexPolyhedron');
+/**
+ * Creates a cylinder-shaped physics body.
+ *
+ * @param getPropFn - Function returning body properties for each instance index
+ * @param ref - Reference to the Three.js Object3D to attach physics to
+ * @param options - Optional configuration for the body
+ * @returns Signal containing the body's public API, or null if not ready
+ *
+ * @example
+ * ```typescript
+ * const mesh = viewChild.required<ElementRef<Mesh>>('mesh');
+ * // args: [radiusTop, radiusBottom, height, numSegments]
+ * const api = cylinder(() => ({ mass: 1, args: [0.5, 0.5, 2, 16], position: [0, 5, 0] }), mesh);
+ * ```
+ */
 const cylinder = createBody('Cylinder');
+/**
+ * Creates a heightfield physics body for terrain simulation.
+ *
+ * @param getPropFn - Function returning body properties for each instance index
+ * @param ref - Reference to the Three.js Object3D to attach physics to
+ * @param options - Optional configuration for the body
+ * @returns Signal containing the body's public API, or null if not ready
+ *
+ * @example
+ * ```typescript
+ * const mesh = viewChild.required<ElementRef<Mesh>>('mesh');
+ * const heightData = [[0, 0, 0], [0, 1, 0], [0, 0, 0]];
+ * const api = heightfield(() => ({
+ *   mass: 0,
+ *   args: [heightData, { elementSize: 1 }],
+ *   position: [0, 0, 0]
+ * }), mesh);
+ * ```
+ */
 const heightfield = createBody('Heightfield');
+/**
+ * Creates a particle (point mass) physics body with no shape.
+ *
+ * @param getPropFn - Function returning body properties for each instance index
+ * @param ref - Reference to the Three.js Object3D to attach physics to
+ * @param options - Optional configuration for the body
+ * @returns Signal containing the body's public API, or null if not ready
+ *
+ * @example
+ * ```typescript
+ * const mesh = viewChild.required<ElementRef<Mesh>>('mesh');
+ * const api = particle(() => ({ mass: 1, position: [0, 5, 0] }), mesh);
+ * ```
+ */
 const particle = createBody('Particle');
+/**
+ * Creates an infinite plane physics body, typically used for floors or walls.
+ *
+ * @param getPropFn - Function returning body properties for each instance index
+ * @param ref - Reference to the Three.js Object3D to attach physics to
+ * @param options - Optional configuration for the body
+ * @returns Signal containing the body's public API, or null if not ready
+ *
+ * @example
+ * ```typescript
+ * const mesh = viewChild.required<ElementRef<Mesh>>('mesh');
+ * const api = plane(() => ({
+ *   mass: 0, // Static body
+ *   rotation: [-Math.PI / 2, 0, 0], // Horizontal
+ *   position: [0, 0, 0]
+ * }), mesh);
+ * ```
+ */
 const plane = createBody('Plane');
+/**
+ * Creates a sphere-shaped physics body.
+ *
+ * @param getPropFn - Function returning body properties for each instance index
+ * @param ref - Reference to the Three.js Object3D to attach physics to
+ * @param options - Optional configuration for the body
+ * @returns Signal containing the body's public API, or null if not ready
+ *
+ * @example
+ * ```typescript
+ * const mesh = viewChild.required<ElementRef<Mesh>>('mesh');
+ * // args: [radius]
+ * const api = sphere(() => ({ mass: 1, args: [1], position: [0, 5, 0] }), mesh);
+ * ```
+ */
 const sphere = createBody('Sphere');
+/**
+ * Creates a trimesh physics body from vertices and indices.
+ * Useful for complex static geometry like terrain or obstacles.
+ *
+ * @param getPropFn - Function returning body properties for each instance index
+ * @param ref - Reference to the Three.js Object3D to attach physics to
+ * @param options - Optional configuration for the body
+ * @returns Signal containing the body's public API, or null if not ready
+ *
+ * @example
+ * ```typescript
+ * const mesh = viewChild.required<ElementRef<Mesh>>('mesh');
+ * const api = trimesh(() => ({
+ *   mass: 0,
+ *   args: [vertices, indices],
+ *   position: [0, 0, 0]
+ * }), mesh);
+ * ```
+ */
 const trimesh = createBody('Trimesh');
+/**
+ * Creates a compound physics body composed of multiple shapes.
+ * Useful for complex objects that can be approximated by combining primitives.
+ *
+ * @param getPropFn - Function returning body properties for each instance index
+ * @param ref - Reference to the Three.js Object3D to attach physics to
+ * @param options - Optional configuration for the body
+ * @returns Signal containing the body's public API, or null if not ready
+ *
+ * @example
+ * ```typescript
+ * const mesh = viewChild.required<ElementRef<Mesh>>('mesh');
+ * const api = compound(() => ({
+ *   mass: 1,
+ *   shapes: [
+ *     { type: 'Box', args: [1, 1, 1], position: [0, 0, 0] },
+ *     { type: 'Sphere', args: [0.5], position: [0, 1, 0] }
+ *   ],
+ *   position: [0, 5, 0]
+ * }), mesh);
+ * ```
+ */
 const compound = createBody('Compound');
 /**
  * @deprecated Use `box` instead. Will be removed in v5.0.0