@phalanx-engine/physics 0.1.0

package/README.md

@@ -0,0 +1,437 @@
+# Phalanx Physics
+
+A deterministic, fixed-point physics engine for the [Phalanx Engine](../README.md). Designed for lockstep multiplayer games where every client must produce identical simulation results.
+
+> Sibling packages: [phalanx-ecs](../phalanx-ecs/README.md) (ECS core), [phalanx-math](../phalanx-math/README.md) (fixed-point math), [phalanx-server](../phalanx-server/README.md), [phalanx-client](../phalanx-client/README.md).
+
+## Features
+
+- **Deterministic by Design**: All math uses `FP.*` fixed-point operations — no floating-point non-determinism
+- **SoA Storage**: Physics body data stored in contiguous typed arrays (`BigInt64Array` for fixed-point, `Uint8Array` for flags) via phalanx-ecs `SoAComponent`
+- **Spatial Hash Grid**: O(n) broad-phase collision detection with configurable cell size
+- **Narrow Phase**: Circle vs Circle, Circle vs AABB, and AABB vs AABB collision tests
+- **Impulse Resolution**: Mass-weighted velocity impulse + positional separation for overlap correction
+- **Sub-stepping**: Configurable physics sub-steps per tick for higher fidelity at the same tick rate
+- **Collision Filtering**: Inject game-specific collision rules via callback — no coupling to game concepts
+- **Tick Providers**: Pluggable `IPhysicsTickProvider` interface decouples tick scheduling from simulation logic — supports GameWorld-driven, autonomous (turn-based), and external (rAF) modes
+- **Impulse API**: `applyImpulse()` sets body velocity for flick/strike mechanics; `isSettled()` queries whether all bodies are at rest
+- **Bounds Exit Mode**: Optional `ejectOnBoundsExit` mode marks out-of-bounds bodies as ignored and emits `BOUNDS_EXIT` events instead of clamping
+- **Event-Driven**: Collision, trigger enter, trigger exit, and bounds exit events emitted via phalanx-ecs `EventBus`
+- **Built-in Transform & Interpolation**: `TransformComponent` (SoA fixed-point spatial state), `InterpolationComponent`, and `InterpolationSystem` for tick-to-frame render smoothing
+- **PhysicsWorld Facade**: One-liner setup — wraps PhysicsSystem + InterpolationSystem, exposes event subscriptions, spatial queries, and interpolated transforms
+
+## Core Components
+
+### PhysicsWorld (Recommended Entry Point)
+- **PhysicsWorld**: High-level facade — creates PhysicsSystem and InterpolationSystem, wires collision pipeline, exposes event subscriptions, spatial queries, and `getInterpolatedTransform()`
+
+### Transform & Interpolation
+- **TransformComponent**: SoA-backed fixed-point position and rotation (`TransformSoASchema`, `TRANSFORM_COMPONENT_TYPE`)
+- **InterpolationComponent**: Tick-to-tick transform samples for render smoothing
+- **InterpolationSystem**: Snapshots/captures transform state each tick and interpolates each frame (implements `IBeforeTick`, `IAfterTick`, `IBeforeFrame`)
+
+### Physics Body
+- **PhysicsBodyComponent**: SoA-backed component with velocity, radius, mass, restitution, friction, isStatic, and ignorePhysics fields
+- **PhysicsSoASchema**: Schema definition for the SoA storage layout
+
+### Collision Detection
+- **SpatialHashGrid**: Broad-phase spatial partitioning with `queryPairs()` and `queryRadius()`
+- **NarrowPhase**: Static methods for precise collision geometry tests
+
+### Systems
+- **PhysicsSystem**: Velocity integration with sub-stepping, world bounds handling, broad/narrow/resolve collision pipeline, `step()` / `applyImpulse()` / `isSettled()` / `setCollisionFilter()` API. Created and owned by `PhysicsWorld`; retrieve it via `physicsWorld.getSystems().physicsSystem` to register with `GameWorld`.
+- **InterpolationSystem**: Tick/frame lifecycle hooks for transform interpolation. Register as a **frame system** via `physicsWorld.getSystems().interpolationSystem`.
+
+### Tick Providers
+- **IPhysicsTickProvider**: Interface for custom tick scheduling strategies
+- **AutonomousPhysicsTickProvider**: Runs physics loop via `setImmediate` (Node.js) or `setTimeout(0)` (browser) until settled or `maxSteps` reached — ideal for turn-based games
+- **ExternalPhysicsTickProvider**: Delegates tick control to the caller (e.g. BabylonJS `onBeforeRenderObservable` or unit tests)
+
+### Events
+- **PhysicsEvents.COLLISION**: Emitted when two bodies collide
+- **PhysicsEvents.TRIGGER_ENTER**: Emitted when a trigger overlap starts
+- **PhysicsEvents.TRIGGER_EXIT**: Emitted when a trigger overlap ends
+- **PhysicsEvents.BOUNDS_EXIT**: Emitted when a body exits `worldBounds` and `ejectOnBoundsExit` is `true`
+
+## Installation
+
+> ⚠️ **Not on npm yet** — clone the monorepo and install via pnpm.
+
+```bash
+git clone https://github.com/phaeton-forge/phalanx-engine.git
+cd phalanx-engine
+pnpm install
+pnpm --filter @phalanx-engine/physics build
+```
+
+Peer dependencies: `@phalanx-engine/ecs` ^0.1.0, `@phalanx-engine/math` ^0.1.0
+
+## Imports
+
+```typescript
+import {
+  // Facade & config
+  PhysicsWorld,
+  type PhysicsWorldConfig,
+
+  // Components
+  PhysicsBodyComponent,
+  PhysicsSoASchema,
+  PHYSICS_BODY_COMPONENT_TYPE,
+  TransformComponent,
+  TransformSoASchema,
+  TRANSFORM_COMPONENT_TYPE,
+  InterpolationComponent,
+  INTERPOLATION_COMPONENT_TYPE,
+  type PhysicsBodyConfig,
+
+  // Collision primitives
+  SpatialHashGrid,
+  NarrowPhase,
+  type CollisionManifold,
+
+  // Systems
+  PhysicsSystem,
+  InterpolationSystem,
+  type InterpolatedTransformSample,
+
+  // Events & event types
+  PhysicsEvents,
+  type CollisionEvent,
+  type BoundsExitEvent,
+
+  // Tick providers
+  type IPhysicsTickProvider,
+  AutonomousPhysicsTickProvider,
+  type AutonomousProviderOptions,
+  ExternalPhysicsTickProvider,
+
+  // Misc types
+  type CollisionFilter,
+  type PhysicsConfig,
+} from '@phalanx-engine/physics';
+```
+
+## Quick Start
+
+```typescript
+import { GameWorld, GameSystem, createComponentTypeRegistry } from '@phalanx-engine/ecs';
+import {
+  PhysicsWorld,
+  PhysicsBodyComponent,
+  TransformComponent,
+  InterpolationComponent,
+  PHYSICS_BODY_COMPONENT_TYPE,
+  TRANSFORM_COMPONENT_TYPE,
+  INTERPOLATION_COMPONENT_TYPE,
+} from '@phalanx-engine/physics';
+import { FP, FPVector3 } from '@phalanx-engine/math';
+
+// Register canonical component type symbols from phalanx-physics
+export const ComponentType = createComponentTypeRegistry({
+  Transform: 'Transform',
+  Interpolation: 'Interpolation',
+  PhysicsBody: 'PhysicsBody',
+});
+(ComponentType as Record<string, symbol>).Transform = TRANSFORM_COMPONENT_TYPE;
+(ComponentType as Record<string, symbol>).Interpolation = INTERPOLATION_COMPONENT_TYPE;
+(ComponentType as Record<string, symbol>).PhysicsBody = PHYSICS_BODY_COMPONENT_TYPE;
+
+// Minimal placeholder systems — replace with your real ones.
+class MovementSystem extends GameSystem {
+  public override processTick(_tick: number): void { /* set velocities here */ }
+}
+class RenderSystem extends GameSystem {
+  public override update(_dt: number): void {
+    const sample = this.physics?.getInterpolatedTransform(entityId);
+    if (sample) mesh.position.set(sample.position.x, sample.position.y, sample.position.z);
+  }
+}
+const movementSystem = new MovementSystem();
+const renderSystem = new RenderSystem();
+
+// 1. Create GameWorld and the physics facade
+const world = new GameWorld({ componentTypes: Object.values(ComponentType) });
+
+const physicsWorld = new PhysicsWorld({
+  gridCellSize: FP.FromFloat(8),
+  subSteps: 3,
+  tickRate: 20,
+  maxVelocity: FP.FromFloat(15),
+  pushStrength: FP.FromFloat(15),
+});
+
+// 2. Wire physics into SystemContext so systems can access it
+world.context.physics = physicsWorld;
+
+// 3. Register systems with GameWorld (order matters)
+const { physicsSystem, interpolationSystem } = physicsWorld.getSystems();
+world.registerSystems(
+  [movementSystem, physicsSystem],   // tick systems
+  [interpolationSystem, renderSystem], // frame systems — InterpolationSystem runs before render
+);
+
+world.start();
+
+// 4. Add transform, interpolation, and physics body to entities
+declare const entity: { id: number; addComponent(c: unknown): void };
+const fpPosition = FPVector3.FromFloat(0, 0, 0);
+entity.addComponent(new TransformComponent(entity.id, fpPosition));
+entity.addComponent(new InterpolationComponent(fpPosition));
+entity.addComponent(new PhysicsBodyComponent(entity.id, { radius: FP.FromFloat(1.0) }));
+world.entityManager.addEntity(entity as any);
+
+// 5. Subscribe to collision events (must be called after world.start())
+physicsWorld.onCollision((event) => {
+  console.log(`Collision: ${event.entityA} ↔ ${event.entityB}`);
+});
+```
+
+> **Note:** `PhysicsSystem` reads and writes the built-in `TransformSoASchema` store directly — no `setTransformStore()` or consumer-defined transform schema is required. Register `Transform`, `Interpolation`, and `PhysicsBody` component types using the canonical symbols exported from phalanx-physics.
+
+## Turn-Based Physics (Tick Providers)
+
+For turn-based games like Chapayev checkers, use a tick provider to decouple simulation from the server tick loop:
+
+```typescript
+import {
+  PhysicsWorld,
+  AutonomousPhysicsTickProvider,
+} from '@phalanx-engine/physics';
+import { FP } from '@phalanx-engine/math';
+
+// Game defines what "settled" means and what happens when it occurs
+let physicsWorld: PhysicsWorld;
+
+const provider = new AutonomousPhysicsTickProvider({
+  isSettled: () => physicsWorld.isSettled(),
+  onSettled: () => {
+    // Game-level logic: turn is over
+    sendTurnEnd(getCheckerPositions());
+  },
+});
+
+physicsWorld = new PhysicsWorld({
+  tickRate: 60,
+  subSteps: 3,
+  ejectOnBoundsExit: true,
+  worldBounds: {
+    minX: FP.FromFloat(-8), maxX: FP.FromFloat(8),
+    minZ: FP.FromFloat(-8), maxZ: FP.FromFloat(8),
+  },
+  tickProvider: provider,
+});
+
+// Player flicks a checker
+function onFlick(entityId: number, dirX: number, dirZ: number, power: number) {
+  const speed = power * 12;
+  physicsWorld.applyImpulse(
+    entityId,
+    FP.FromFloat(dirX * speed),
+    FP.FromFloat(dirZ * speed),
+  );
+}
+
+// Checker exits the board
+physicsWorld.onBoundsExit(({ entityId }) => {
+  removeChecker(entityId);
+});
+```
+
+### Tick Provider Options
+
+| Provider | Use Case |
+|---|---|
+| *(none / default)* | GameWorld `processTick()` drives simulation — real-time games |
+| `AutonomousPhysicsTickProvider` | Runs until settled or `maxSteps` — turn-based physics |
+| `ExternalPhysicsTickProvider` | Caller invokes `tick()` manually — BabylonJS rAF, unit tests |
+
+## API Reference
+
+### `PhysicsWorld`
+
+```typescript
+class PhysicsWorld {
+  constructor(config?: PhysicsWorldConfig);
+
+  // System wiring
+  getSystems(): { physicsSystem: PhysicsSystem; interpolationSystem: InterpolationSystem };
+  setCollisionFilter(filter: (entityA: number, entityB: number) => boolean): void;
+
+  // Event subscriptions (must be called after GameWorld.start())
+  onCollision(callback: (event: CollisionEvent) => void): () => void;
+  onBoundsExit(callback: (event: BoundsExitEvent) => void): () => void;
+
+  // Planned — not yet emitted by PhysicsSystem.
+  onTriggerEnter(callback: (event: CollisionEvent) => void): () => void;
+  onTriggerExit(callback: (event: CollisionEvent) => void): () => void;
+
+  // Impulse / settle queries
+  applyImpulse(entityId: number, vx: FixedPoint, vz: FixedPoint): void;
+  isSettled(threshold?: FixedPoint): boolean;
+
+  // Spatial / transform queries
+  readonly spatialGrid: SpatialHashGrid;
+  getEntityPosition(entityId: number): { x: FixedPoint; z: FixedPoint } | undefined;
+  getInterpolatedTransform(entityId: number): InterpolatedTransformSample | undefined;
+
+  // Cleanup
+  dispose(): void;
+}
+```
+
+- **`getSystems()`** — Returns both `physicsSystem` (register as tick system) and `interpolationSystem` (register as frame system).
+- **`getEntityPosition(entityId)`** — Fixed-point position for gameplay queries (e.g. ability targeting).
+- **`getInterpolatedTransform(entityId)`** — Interpolated float position/rotation for rendering, populated after `InterpolationSystem` runs.
+
+- **`applyImpulse(entityId, vx, vz)`** — Set body velocity (replaces, does not accumulate). Re-enables previously ejected bodies.
+- **`isSettled(threshold?)`** — Pure query: `true` when all non-static, non-ignored bodies are below velocity threshold (default from config, falling back to `FP.FromFloat(0.01)`).
+- **`onBoundsExit(callback)`** — Subscribe to `BOUNDS_EXIT` events (requires `ejectOnBoundsExit: true`).
+- **`setCollisionFilter(filter)`** — Inject a per-pair predicate. Return `false` to skip collision resolution for that pair.
+
+### `PhysicsWorldConfig`
+
+```typescript
+interface PhysicsWorldConfig {
+  gridCellSize?: FixedPoint;     // default FP.FromFloat(4)
+  subSteps?: number;             // default 3
+  tickRate?: number;             // default 20 — used to compute tickDt
+  worldBounds?: { minX: FixedPoint; minZ: FixedPoint; maxX: FixedPoint; maxZ: FixedPoint };
+  defaultRestitution?: FixedPoint;
+  defaultFriction?: FixedPoint;  // default FP.FromFloat(0.92)
+  maxVelocity?: FixedPoint;      // default FP.FromFloat(15)
+  pushStrength?: FixedPoint;     // default FP.FromFloat(15)
+  tickProvider?: IPhysicsTickProvider;
+  ejectOnBoundsExit?: boolean;   // default false
+  settleThreshold?: FixedPoint;  // default FP.FromFloat(0.01)
+}
+```
+
+### `TransformComponent`
+
+```typescript
+class TransformComponent extends SoAComponent<typeof TransformSoASchema.definition> {
+  static readonly soaSchema: typeof TransformSoASchema;
+  readonly type: symbol; // TRANSFORM_COMPONENT_TYPE
+
+  constructor(entityId: number, initialPosition?: FPVector3, initialRotation?: FPVector3);
+
+  fpPosition: FPVector3;   // get/set — authoritative fixed-point position
+  fpRotation: FPVector3;   // get/set — authoritative fixed-point rotation (radians)
+  fpRotationY: FixedPoint; // get/set — convenience for Y-axis rotation
+}
+```
+
+`TransformSoASchema` fields: `fpPositionX/Y/Z`, `fpRotationX/Y/Z` (all `i64`).
+
+### `InterpolationComponent`
+
+```typescript
+class InterpolationComponent implements IComponent {
+  readonly type: symbol; // INTERPOLATION_COMPONENT_TYPE
+
+  constructor(initialPosition?: FPVector3, initialRotation?: FPVector3);
+
+  snapshot(): void;  // copy current → previous (called by InterpolationSystem before tick)
+  capture(fpPosition: FPVector3, fpRotation: FPVector3): void; // capture authoritative state after tick
+}
+```
+
+Attach alongside `TransformComponent` on any entity that needs render interpolation.
+
+### `PhysicsBodyComponent`
+
+```typescript
+class PhysicsBodyComponent extends SoAComponent<typeof PhysicsSoASchema.definition> {
+  static readonly soaSchema: typeof PhysicsSoASchema;
+  readonly type: symbol; // PHYSICS_BODY_COMPONENT_TYPE
+
+  constructor(entityId: number, config: PhysicsBodyConfig);
+
+  // Velocity
+  velocity: FPVector3;                                       // get/set (returns cached object)
+  setVelocity(x: FixedPoint, y: FixedPoint, z: FixedPoint): void;
+  addVelocity(velocity: FPVector3): void;
+  stopVelocity(): void;
+
+  // Read-only attributes
+  readonly radius: FixedPoint;
+  readonly radiusFloat: number;
+  readonly mass: FixedPoint;
+  readonly restitution: FixedPoint;
+  readonly friction: FixedPoint;
+  readonly isStatic: boolean;
+  ignorePhysics: boolean;        // get/set
+
+  // Spatial-grid bookkeeping
+  lastX: number;
+  lastZ: number;
+}
+
+interface PhysicsBodyConfig {
+  radius: FixedPoint;
+  mass?: FixedPoint;             // default FP._1
+  isStatic?: boolean;            // default false
+  restitution?: FixedPoint;      // default FP.FromFloat(0.5)
+  friction?: FixedPoint;         // default FP._0
+}
+```
+
+For hot-path access, prefer the SoA store directly:
+
+```typescript
+const store = entityManager.getOrCreateSoAStore(PhysicsSoASchema);
+const idx = store.indexOf(entityId);
+store.arrays.velocityX[idx] = FP.ToRaw(newVx);
+```
+
+### Collision primitives
+
+- **`SpatialHashGrid`** — broad-phase O(n) neighbor pairing. Methods: `clear()`, `insert(...)`, `queryPairs()`, `queryRadius(...)`. Access via `physicsWorld.spatialGrid` for ad-hoc range queries.
+- **`NarrowPhase`** — static methods for circle/AABB intersection tests. Returns `CollisionManifold | null`.
+- **`CollisionManifold`** — `{ entityA, entityB, normalX, normalZ, penetration }`.
+
+### Tick providers
+
+```typescript
+interface IPhysicsTickProvider {
+  /** Start the provider; it calls `onStep` whenever physics should advance one step. */
+  start(onStep: () => void): void;
+  /** Stop the provider and release any timers/handles. */
+  stop(): void;
+}
+
+interface AutonomousProviderOptions {
+  /** Called every step to decide whether to stop (defined by the game). */
+  isSettled: () => boolean;
+  /** Called once when simulation settles or `maxSteps` is reached. */
+  onSettled: () => void;
+  /** Max simulation steps before forcing a stop. Default: 10000. */
+  maxSteps?: number;
+}
+
+class AutonomousPhysicsTickProvider implements IPhysicsTickProvider {
+  constructor(options: AutonomousProviderOptions);
+  // Schedules `onStep` via setImmediate (Node) or setTimeout(0) (browser)
+  // until isSettled() returns true or maxSteps is reached.
+}
+
+class ExternalPhysicsTickProvider implements IPhysicsTickProvider {
+  /** Manually advance one physics step from your render loop / test harness. */
+  tick(): void;
+}
+```
+
+### Events
+
+```typescript
+const PhysicsEvents = {
+  COLLISION:     'physics:collision',
+  TRIGGER_ENTER: 'physics:trigger:enter',
+  TRIGGER_EXIT:  'physics:trigger:exit',
+  BOUNDS_EXIT:   'physics:bounds:exit',
+} as const;
+
+interface CollisionEvent { entityA: number; entityB: number; manifold: CollisionManifold; }
+interface BoundsExitEvent { entityId: number; }
+```

package/dist/PhysicsWorld.d.ts

@@ -0,0 +1,35 @@
+import { PhysicsSystem } from './systems/PhysicsSystem';
+import { InterpolationSystem } from './systems/InterpolationSystem';
+import type { InterpolatedTransformSample } from './systems/InterpolationSystem';
+import { SpatialHashGrid } from './collision/SpatialHashGrid';
+import type { PhysicsWorldConfig } from './PhysicsWorldConfig';
+import type { FixedPoint } from '@phalanx-engine/math';
+import type { CollisionEvent, BoundsExitEvent } from './types';
+export declare class PhysicsWorld {
+    private readonly physicsSystem;
+    private readonly interpolationSystem;
+    private eventBusRef;
+    private readonly unsubscribers;
+    private readonly settleThreshold;
+    constructor(config?: PhysicsWorldConfig);
+    getSystems(): {
+        physicsSystem: PhysicsSystem;
+        interpolationSystem: InterpolationSystem;
+    };
+    setCollisionFilter(filter: (entityA: number, entityB: number) => boolean): void;
+    onCollision(callback: (event: CollisionEvent) => void): () => void;
+    onTriggerEnter(callback: (event: CollisionEvent) => void): () => void;
+    onTriggerExit(callback: (event: CollisionEvent) => void): () => void;
+    applyImpulse(entityId: number, vx: FixedPoint, vz: FixedPoint): void;
+    isSettled(threshold?: FixedPoint): boolean;
+    onBoundsExit(callback: (event: BoundsExitEvent) => void): () => void;
+    get spatialGrid(): SpatialHashGrid;
+    getEntityPosition(entityId: number): {
+        x: FixedPoint;
+        z: FixedPoint;
+    } | undefined;
+    getInterpolatedTransform(entityId: number): InterpolatedTransformSample | undefined;
+    dispose(): void;
+    private getEventBus;
+}
+//# sourceMappingURL=PhysicsWorld.d.ts.map

package/dist/PhysicsWorld.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PhysicsWorld.d.ts","sourceRoot":"","sources":["../src/PhysicsWorld.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAiB,eAAe,EAAE,MAAM,SAAS,CAAC;AAS9E,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAsB;IAC1D,OAAO,CAAC,WAAW,CAAyB;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsB;IACpD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyB;gBAE7C,MAAM,CAAC,EAAE,kBAAkB;IAgChC,UAAU,IAAI;QACnB,aAAa,EAAE,aAAa,CAAC;QAC7B,mBAAmB,EAAE,mBAAmB,CAAC;KAC1C;IAWM,kBAAkB,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI;IAS/E,WAAW,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI;IAalE,cAAc,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI;IAarE,aAAa,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI;IAWpE,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,GAAG,IAAI;IAQpE,SAAS,CAAC,SAAS,CAAC,EAAE,UAAU,GAAG,OAAO;IAK1C,YAAY,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI;IAS3E,IAAW,WAAW,IAAI,eAAe,CAExC;IAKM,iBAAiB,CACtB,QAAQ,EAAE,MAAM,GACf;QAAE,CAAC,EAAE,UAAU,CAAC;QAAC,CAAC,EAAE,UAAU,CAAA;KAAE,GAAG,SAAS;IAQxC,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,2BAA2B,GAAG,SAAS;IAKnF,OAAO,IAAI,IAAI;IAOtB,OAAO,CAAC,WAAW;CASpB"}

package/dist/PhysicsWorld.js

@@ -0,0 +1,112 @@
+import { FP } from '@phalanx-engine/math';
+import { PhysicsSystem } from './systems/PhysicsSystem';
+import { InterpolationSystem } from './systems/InterpolationSystem';
+import { PhysicsEvents } from './events';
+export class PhysicsWorld {
+    physicsSystem;
+    interpolationSystem;
+    eventBusRef = null;
+    unsubscribers = [];
+    settleThreshold;
+    constructor(config) {
+        const tickRate = config?.tickRate ?? 20;
+        const subSteps = config?.subSteps ?? 3;
+        const tickDt = FP.FromFloat(1 / tickRate);
+        const gridCellSize = config?.gridCellSize ?? FP.FromFloat(4);
+        const maxVelocity = config?.maxVelocity ?? FP.FromFloat(15.0);
+        const pushStrength = config?.pushStrength ?? FP.FromFloat(15.0);
+        const defaultFriction = config?.defaultFriction ?? FP.FromFloat(0.92);
+        const physicsConfig = {
+            tickDt,
+            subSteps,
+            maxVelocity,
+            defaultFriction,
+            pushStrength,
+            gridCellSize,
+            worldBounds: config?.worldBounds,
+            ejectOnBoundsExit: config?.ejectOnBoundsExit,
+        };
+        this.physicsSystem = new PhysicsSystem(physicsConfig);
+        this.interpolationSystem = new InterpolationSystem();
+        this.settleThreshold = config?.settleThreshold;
+        if (config?.tickProvider) {
+            this.physicsSystem.setTickProvider(config.tickProvider);
+        }
+    }
+    getSystems() {
+        return {
+            physicsSystem: this.physicsSystem,
+            interpolationSystem: this.interpolationSystem,
+        };
+    }
+    setCollisionFilter(filter) {
+        this.physicsSystem.setCollisionFilter(filter);
+    }
+    onCollision(callback) {
+        const eb = this.getEventBus();
+        if (!eb) {
+            throw new Error('PhysicsWorld: Cannot subscribe before systems are initialized');
+        }
+        const unsub = eb.on(PhysicsEvents.COLLISION, callback);
+        this.unsubscribers.push(unsub);
+        return unsub;
+    }
+    onTriggerEnter(callback) {
+        const eb = this.getEventBus();
+        if (!eb) {
+            throw new Error('PhysicsWorld: Cannot subscribe before systems are initialized');
+        }
+        const unsub = eb.on(PhysicsEvents.TRIGGER_ENTER, callback);
+        this.unsubscribers.push(unsub);
+        return unsub;
+    }
+    onTriggerExit(callback) {
+        const eb = this.getEventBus();
+        if (!eb) {
+            throw new Error('PhysicsWorld: Cannot subscribe before systems are initialized');
+        }
+        const unsub = eb.on(PhysicsEvents.TRIGGER_EXIT, callback);
+        this.unsubscribers.push(unsub);
+        return unsub;
+    }
+    applyImpulse(entityId, vx, vz) {
+        this.physicsSystem.applyImpulse(entityId, vx, vz);
+    }
+    isSettled(threshold) {
+        return this.physicsSystem.isSettled(threshold ?? this.settleThreshold);
+    }
+    onBoundsExit(callback) {
+        const eb = this.getEventBus();
+        if (!eb)
+            throw new Error('PhysicsWorld: Cannot subscribe before systems are initialized');
+        const unsub = eb.on(PhysicsEvents.BOUNDS_EXIT, callback);
+        this.unsubscribers.push(unsub);
+        return unsub;
+    }
+    get spatialGrid() {
+        return this.physicsSystem.getSpatialGrid();
+    }
+    getEntityPosition(entityId) {
+        return this.physicsSystem.getEntityPosition(entityId);
+    }
+    getInterpolatedTransform(entityId) {
+        return this.interpolationSystem.getInterpolatedTransform(entityId);
+    }
+    dispose() {
+        for (const unsub of this.unsubscribers) {
+            unsub();
+        }
+        this.unsubscribers.length = 0;
+    }
+    getEventBus() {
+        if (this.eventBusRef)
+            return this.eventBusRef;
+        try {
+            this.eventBusRef = this.physicsSystem.getEventBus() ?? null;
+        }
+        catch {
+            return null;
+        }
+        return this.eventBusRef;
+    }
+}

package/dist/PhysicsWorldConfig.d.ts

@@ -0,0 +1,21 @@
+import type { FixedPoint } from '@phalanx-engine/math';
+import type { IPhysicsTickProvider } from './tick/IPhysicsTickProvider';
+export interface PhysicsWorldConfig {
+    gridCellSize?: FixedPoint;
+    subSteps?: number;
+    tickRate?: number;
+    worldBounds?: {
+        minX: FixedPoint;
+        minZ: FixedPoint;
+        maxX: FixedPoint;
+        maxZ: FixedPoint;
+    };
+    defaultRestitution?: FixedPoint;
+    defaultFriction?: FixedPoint;
+    maxVelocity?: FixedPoint;
+    pushStrength?: FixedPoint;
+    tickProvider?: IPhysicsTickProvider;
+    ejectOnBoundsExit?: boolean;
+    settleThreshold?: FixedPoint;
+}
+//# sourceMappingURL=PhysicsWorldConfig.d.ts.map

package/dist/PhysicsWorldConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PhysicsWorldConfig.d.ts","sourceRoot":"","sources":["../src/PhysicsWorldConfig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAKxE,MAAM,WAAW,kBAAkB;IAEjC,YAAY,CAAC,EAAE,UAAU,CAAC;IAE1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,WAAW,CAAC,EAAE;QACZ,IAAI,EAAE,UAAU,CAAC;QACjB,IAAI,EAAE,UAAU,CAAC;QACjB,IAAI,EAAE,UAAU,CAAC;QACjB,IAAI,EAAE,UAAU,CAAC;KAClB,CAAC;IAEF,kBAAkB,CAAC,EAAE,UAAU,CAAC;IAEhC,eAAe,CAAC,EAAE,UAAU,CAAC;IAE7B,WAAW,CAAC,EAAE,UAAU,CAAC;IAEzB,YAAY,CAAC,EAAE,UAAU,CAAC;IAQ1B,YAAY,CAAC,EAAE,oBAAoB,CAAC;IAMpC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAO5B,eAAe,CAAC,EAAE,UAAU,CAAC;CAC9B"}

package/dist/PhysicsWorldConfig.js

@@ -0,0 +1 @@
+export {};

package/dist/collision/CollisionManifold.d.ts

@@ -0,0 +1,9 @@
+import type { FixedPoint } from '@phalanx-engine/math';
+export interface CollisionManifold {
+    entityA: number;
+    entityB: number;
+    normalX: FixedPoint;
+    normalZ: FixedPoint;
+    penetration: FixedPoint;
+}
+//# sourceMappingURL=CollisionManifold.d.ts.map

package/dist/collision/CollisionManifold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CollisionManifold.d.ts","sourceRoot":"","sources":["../../src/collision/CollisionManifold.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAKvD,MAAM,WAAW,iBAAiB;IAEhC,OAAO,EAAE,MAAM,CAAC;IAEhB,OAAO,EAAE,MAAM,CAAC;IAEhB,OAAO,EAAE,UAAU,CAAC;IAEpB,OAAO,EAAE,UAAU,CAAC;IAEpB,WAAW,EAAE,UAAU,CAAC;CACzB"}

package/dist/collision/CollisionManifold.js

@@ -0,0 +1 @@
+export {};

package/dist/collision/NarrowPhase.d.ts

@@ -0,0 +1,8 @@
+import { type FixedPoint } from '@phalanx-engine/math';
+import type { CollisionManifold } from './CollisionManifold';
+export declare class NarrowPhase {
+    static circleVsCircle(posAX: FixedPoint, posAZ: FixedPoint, radiusA: FixedPoint, posBX: FixedPoint, posBZ: FixedPoint, radiusB: FixedPoint, entityA: number, entityB: number): CollisionManifold | null;
+    static circleVsAABB(circlePosX: FixedPoint, circlePosZ: FixedPoint, circleRadius: FixedPoint, aabbMinX: FixedPoint, aabbMinZ: FixedPoint, aabbMaxX: FixedPoint, aabbMaxZ: FixedPoint, entityCircle: number, entityAABB: number): CollisionManifold | null;
+    static aabbVsAABB(aMinX: FixedPoint, aMinZ: FixedPoint, aMaxX: FixedPoint, aMaxZ: FixedPoint, bMinX: FixedPoint, bMinZ: FixedPoint, bMaxX: FixedPoint, bMaxZ: FixedPoint, entityA: number, entityB: number): CollisionManifold | null;
+}
+//# sourceMappingURL=NarrowPhase.d.ts.map

package/dist/collision/NarrowPhase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NarrowPhase.d.ts","sourceRoot":"","sources":["../../src/collision/NarrowPhase.ts"],"names":[],"mappings":"AAAA,OAAO,EAAM,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAW7D,qBAAa,WAAW;IAKtB,MAAM,CAAC,cAAc,CACnB,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EACzD,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EACzD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAC/B,iBAAiB,GAAG,IAAI;IAwC3B,MAAM,CAAC,YAAY,CACjB,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EACxE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAC1C,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAC1C,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GACvC,iBAAiB,GAAG,IAAI;IAsE3B,MAAM,CAAC,UAAU,CACf,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAC1E,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,EAC1E,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAC/B,iBAAiB,GAAG,IAAI;CAuC5B"}