@ue-too/dynamics 0.9.5 → 0.11.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ue-too/dynamics",
   "type": "module",
-  "version": "0.9.5",
+  "version": "0.11.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -20,8 +20,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@ue-too/math": "^0.9.5",
-    "@ue-too/ecs": "^0.9.5"
+    "@ue-too/math": "^0.11.0",
+    "@ue-too/ecs": "^0.11.0"
   },
   "main": "./index.js",
   "types": "./index.d.ts",

package/pair-manager.d.ts

@@ -1,5 +1,14 @@
 import { RigidBody } from "./rigidbody";
 import { Point } from "@ue-too/math";
+/**
+ * Represents a collision pair between two bodies.
+ *
+ * @remarks
+ * Tracks collision information across multiple frames, enabling
+ * detection of collision start, update, and end events.
+ *
+ * @category Collision
+ */
 export interface CollisionPair {
     bodyA: RigidBody;
     bodyB: RigidBody;
@@ -16,6 +25,33 @@ export interface PairEvents {
     updated: CollisionPair[];
     removed: CollisionPair[];
 }
+/**
+ * Manages collision pairs across frames.
+ *
+ * @remarks
+ * Tracks which bodies are colliding and for how long, enabling
+ * collision lifecycle events (start, update, end). This is useful for
+ * game logic like damage on collision start or triggers.
+ *
+ * Automatically cleans up old inactive pairs to prevent memory leaks.
+ *
+ * @example
+ * Using collision events
+ * ```typescript
+ * const pairManager = world.getPairManager();
+ *
+ * world.step(dt);
+ *
+ * const events = pairManager.getActivePairs();
+ * events.forEach(pair => {
+ *   if (pair.frameCreated === world.currentFrame) {
+ *     console.log('Collision started!');
+ *   }
+ * });
+ * ```
+ *
+ * @category Collision
+ */
 export declare class PairManager {
     private pairs;
     private frameNumber;

package/quadtree.d.ts

@@ -10,6 +10,10 @@ export declare class RectangleBound {
     getbottomLeft(): Point;
 }
 export type QuadTreeObject = SpatialIndexObject;
+/**
+ * QuadTree spatial indexing structure for efficient collision detection.
+ * @category Spatial Indexing
+ */
 export declare class QuadTree<T extends QuadTreeObject> implements SpatialIndex<T> {
     private MAX_OBJECTS;
     private MAX_LEVELS;

package/rigidbody.d.ts

@@ -1,17 +1,38 @@
 import { Point } from "@ue-too/math";
 import { CollisionFilter } from "./collision-filter";
+/**
+ * Rigid body interface for 2D physics simulation.
+ *
+ * @remarks
+ * Represents a physical object in the physics world with mass, velocity,
+ * rotation, and collision properties. Can be either static (immovable) or
+ * dynamic (responds to forces).
+ *
+ * Implemented by {@link Circle} and {@link Polygon} classes.
+ *
+ * @category Core
+ */
 export interface RigidBody {
+    /** Center position in world coordinates */
     center: Point;
+    /** Rotation angle in radians */
     orientationAngle: number;
+    /** Linear velocity (pixels/second) */
     linearVelocity: Point;
+    /** Angular velocity (radians/second) */
     angularVelocity: number;
+    /** Axis-Aligned Bounding Box for broad phase collision */
     AABB: {
         min: Point;
         max: Point;
     };
+    /** Mass in arbitrary units (affects force response) */
     mass: number;
+    /** Static friction coefficient (0-1) */
     staticFrictionCoeff: number;
+    /** Moment of inertia (rotational mass) */
     momentOfInertia: number;
+    /** Collision filtering configuration */
     collisionFilter: CollisionFilter;
     isSleeping: boolean;
     sleepThreshold: number;

package/world.d.ts

@@ -2,7 +2,58 @@ import { RigidBody } from "./rigidbody";
 import { Point } from "@ue-too/math";
 import { Constraint } from "./constraint";
 import { PairManager } from "./pair-manager";
+/**
+ * Spatial indexing algorithm types.
+ *
+ * @remarks
+ * Different algorithms have different performance characteristics:
+ * - **quadtree**: Best for static or mostly-static worlds
+ * - **dynamictree**: Good balance for mixed static/dynamic
+ * - **sap**: Best for many dynamic bodies (sweep-and-prune)
+ *
+ * @category Core
+ */
 export type SpatialIndexType = 'quadtree' | 'dynamictree' | 'sap';
+/**
+ * Main physics world managing rigid body simulation.
+ *
+ * @remarks
+ * The World class is the main entry point for physics simulation. It manages
+ * all rigid bodies, runs collision detection and response, enforces constraints,
+ * and provides performance optimizations like sleeping and spatial indexing.
+ *
+ * ### Simulation Loop
+ *
+ * Call `world.step(deltaTime)` each frame to advance the simulation. This:
+ * 1. Updates sleeping states
+ * 2. Detects collisions (broad and narrow phase)
+ * 3. Resolves collisions with impulses
+ * 4. Enforces constraints
+ * 5. Updates body positions and velocities
+ *
+ * ### Performance Tuning
+ *
+ * - Choose appropriate spatial index for your use case
+ * - Enable sleeping for better performance with many bodies
+ * - Use collision filtering to reduce collision checks
+ *
+ * @example
+ * Basic setup
+ * ```typescript
+ * const world = new World(2000, 2000, 'dynamictree');
+ *
+ * // Add bodies
+ * const ball = new Circle({ x: 0, y: 100 }, 20, 0, 10, false);
+ * world.addRigidBody('ball', ball);
+ *
+ * // Simulation loop
+ * function update(dt: number) {
+ *   world.step(dt);
+ * }
+ * ```
+ *
+ * @category Core
+ */
 export declare class World {
     private rigidBodyList;
     private rigidBodyMap;