@downdraft/engine 0.0.0 → 0.1.1

package/core/src/physics/realm-worker-pool.ts

@@ -0,0 +1,191 @@
+import type { BodyDesc, ColliderDesc, Entity } from "./interface";
+import { RealmTier } from "./interface";
+import { RealmWorker, supportsNestedWorkers, supportsSharedArrayBuffer } from "./realm-worker";
+import type { RealmWorkerRequest } from "./worker-protocol";
+
+/**
+ * Pool of realm workers for parallel mid/far realm simulation.
+ *
+ * The near realm always runs on the sim thread (tightest latency).
+ * Mid/far realms are delegated to workers when `workerCount > 0`.
+ *
+ * `workerCount: 0` = single-threaded fallback (all realms on sim thread).
+ */
+export class RealmWorkerPool {
+  private workers: Map<RealmTier, RealmWorker> = new Map();
+  private workerUrl: string | URL;
+  private workerCount: number;
+  private useSharedBuffer: boolean;
+  private initialized: boolean = false;
+
+  constructor(opts: { workerUrl: string | URL; workerCount?: number }) {
+    this.workerUrl = opts.workerUrl;
+    this.workerCount = opts.workerCount ?? 0;
+    this.useSharedBuffer = supportsSharedArrayBuffer() && supportsNestedWorkers();
+  }
+
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  isParallel(): boolean {
+    return this.workers.size > 0;
+  }
+
+  supportsSharedBuffer(): boolean {
+    return this.useSharedBuffer;
+  }
+
+  /**
+   * Initialize workers for mid/far realms. Returns true if workers are
+   * available; false if single-threaded fallback should be used.
+   */
+  async init(): Promise<boolean> {
+    if (this.workerCount === 0) {
+      this.initialized = true;
+      return false;
+    }
+
+    if (!supportsNestedWorkers()) {
+      // Single-threaded fallback
+      this.initialized = true;
+      return false;
+    }
+
+    try {
+      // Create one worker per tier (mid, far) up to workerCount
+      const tiers = [RealmTier.Mid, RealmTier.Far];
+      for (let i = 0; i < Math.min(this.workerCount, tiers.length); i++) {
+        const tier = tiers[i];
+        const worker = new RealmWorker(this.workerUrl, tier);
+        this.workers.set(tier, worker);
+      }
+      this.initialized = true;
+      return this.workers.size > 0;
+    } catch {
+      this.initialized = true;
+      return false;
+    }
+  }
+
+  hasWorkerForTier(tier: RealmTier): boolean {
+    return this.workers.has(tier);
+  }
+
+  getWorker(tier: RealmTier): RealmWorker | undefined {
+    return this.workers.get(tier);
+  }
+
+  /**
+   * Initialize a realm on the appropriate worker.
+   */
+  async initRealm(tier: RealmTier, realmId: number, gravity: [number, number, number]): Promise<boolean> {
+    const worker = this.workers.get(tier);
+    if (!worker) return false;
+    worker.addRealm(realmId);
+    const req: RealmWorkerRequest = { type: "INIT_REALM", realmId, tier, gravity };
+    await worker.request(req);
+    return true;
+  }
+
+  /**
+   * Step a realm on its worker. Returns the wall time in ms, or 0 if
+   * no worker is available (caller should step in-process).
+   */
+  async stepRealm(tier: RealmTier, realmId: number, dt: number, solverIterations: number): Promise<number> {
+    const worker = this.workers.get(tier);
+    if (!worker || !worker.hasRealm(realmId)) return 0;
+    const req: RealmWorkerRequest = { type: "STEP_REALM", realmId, dt, solverIterations };
+    const resp = await worker.request(req);
+    if (resp.type === "STEP_RESULT") return resp.wallTimeMs;
+    return 0;
+  }
+
+  /**
+   * Create a body on the worker for the given realm.
+   */
+  async createBody(tier: RealmTier, realmId: number, bodyId: number, desc: BodyDesc, entity: Entity): Promise<boolean> {
+    const worker = this.workers.get(tier);
+    if (!worker) return false;
+    const req: RealmWorkerRequest = { type: "CREATE_BODY", realmId, bodyId, desc, entity };
+    const resp = await worker.request(req);
+    return resp.type === "CREATE_BODY_RESULT" && resp.success;
+  }
+
+  /**
+   * Destroy a body on the worker.
+   */
+  async destroyBody(tier: RealmTier, realmId: number, bodyId: number): Promise<void> {
+    const worker = this.workers.get(tier);
+    if (!worker) return;
+    const req: RealmWorkerRequest = { type: "DESTROY_BODY", realmId, bodyId };
+    await worker.request(req);
+  }
+
+  /**
+   * Add a collider on the worker.
+   */
+  async addCollider(tier: RealmTier, realmId: number, bodyId: number, colliderId: number, desc: ColliderDesc): Promise<boolean> {
+    const worker = this.workers.get(tier);
+    if (!worker) return false;
+    const req: RealmWorkerRequest = { type: "ADD_COLLIDER", realmId, bodyId, colliderId, desc };
+    const resp = await worker.request(req);
+    return resp.type === "ADD_COLLIDER_RESULT" && resp.success;
+  }
+
+  /**
+   * Read transforms from the worker into the provided buffer.
+   * The buffer is transferred to the worker and back.
+   */
+  async readTransforms(tier: RealmTier, realmId: number, buffer: Float32Array, entityCount: number): Promise<Float32Array> {
+    const worker = this.workers.get(tier);
+    if (!worker) return buffer;
+    const req: RealmWorkerRequest = { type: "READ_TRANSFORMS", realmId, buffer, entityCount };
+    const resp = await worker.request(req, [buffer.buffer]);
+    if (resp.type === "READ_TRANSFORMS_RESULT") return resp.buffer;
+    return buffer;
+  }
+
+  /**
+   * Snapshot a realm on the worker.
+   */
+  async snapshotRealm(tier: RealmTier, realmId: number): Promise<Uint8Array | null> {
+    const worker = this.workers.get(tier);
+    if (!worker) return null;
+    const req: RealmWorkerRequest = { type: "SNAPSHOT_REALM", realmId };
+    const resp = await worker.request(req);
+    if (resp.type === "SNAPSHOT_RESULT") return resp.data;
+    return null;
+  }
+
+  /**
+   * Restore a realm on the worker from snapshot data.
+   */
+  async restoreRealm(tier: RealmTier, realmId: number, data: Uint8Array): Promise<boolean> {
+    const worker = this.workers.get(tier);
+    if (!worker) return false;
+    const req: RealmWorkerRequest = { type: "RESTORE_REALM", realmId, data };
+    const resp = await worker.request(req, [data.buffer]);
+    return resp.type === "RESTORE_REALM_RESULT" && resp.success;
+  }
+
+  /**
+   * Destroy a realm on the worker.
+   */
+  async destroyRealm(tier: RealmTier, realmId: number): Promise<void> {
+    const worker = this.workers.get(tier);
+    if (!worker) return;
+    worker.removeRealm(realmId);
+    const req: RealmWorkerRequest = { type: "DESTROY_REALM", realmId };
+    await worker.request(req);
+  }
+
+  destroy(): void {
+    for (const worker of this.workers.values()) {
+      worker.terminate();
+    }
+    this.workers.clear();
+    this.initialized = false;
+  }
+}
+

package/core/src/physics/realm-worker.ts

@@ -0,0 +1,102 @@
+import type { RealmTier } from "./interface";
+import type { RealmWorkerRequest, RealmWorkerResponse } from "./worker-protocol";
+
+/**
+ * Wraps a single Web Worker that owns one or more physics realm `World`
+ * instances. The host communicates via postMessage; transform buffers are
+ * transferred (not copied) where possible.
+ *
+ * If `SharedArrayBuffer` is available, transform buffers can be shared
+ * between host and worker (zero-copy reads). Otherwise, buffers are
+ * transferred back and forth.
+ */
+export class RealmWorker {
+  private worker: Worker;
+  private nextRequestId: number = 0;
+  private pending: Map<number, { resolve: (resp: RealmWorkerResponse) => void; reject: (err: Error) => void }> = new Map();
+  private realmIds: Set<number> = new Set();
+  public readonly tier: RealmTier;
+
+  constructor(workerUrl: string | URL, tier: RealmTier) {
+    this.tier = tier;
+    this.worker = new Worker(workerUrl, { type: "module" });
+    this.worker.onmessage = (e: MessageEvent) => {
+      const resp = e.data as RealmWorkerResponse & { requestId?: number };
+      if (resp.requestId !== undefined) {
+        const pending = this.pending.get(resp.requestId);
+        if (pending) {
+          this.pending.delete(resp.requestId);
+          pending.resolve(resp);
+        }
+      }
+    };
+    this.worker.onerror = (e) => {
+      // Reject all pending requests on error
+      for (const [, pending] of this.pending.entries()) {
+        pending.reject(new Error(`Worker error: ${e.message}`));
+      }
+      this.pending.clear();
+    };
+  }
+
+  hasRealm(realmId: number): boolean {
+    return this.realmIds.has(realmId);
+  }
+
+  addRealm(realmId: number): void {
+    this.realmIds.add(realmId);
+  }
+
+  removeRealm(realmId: number): void {
+    this.realmIds.delete(realmId);
+  }
+
+  /**
+   * Send a request to the worker and await the response.
+   * Transferable buffers are transferred (not copied).
+   */
+  request(req: RealmWorkerRequest, transfer: Transferable[] = []): Promise<RealmWorkerResponse> {
+    const requestId = this.nextRequestId++;
+    return new Promise((resolve, reject) => {
+      this.pending.set(requestId, { resolve, reject });
+      this.worker.postMessage({ ...req, requestId }, transfer);
+    });
+  }
+
+  /**
+   * Send a fire-and-forget message (no response expected).
+   */
+  notify(req: RealmWorkerRequest, transfer: Transferable[] = []): void {
+    this.worker.postMessage(req, transfer);
+  }
+
+  terminate(): void {
+    this.worker.terminate();
+    for (const [, pending] of this.pending.entries()) {
+      pending.reject(new Error("Worker terminated"));
+    }
+    this.pending.clear();
+    this.realmIds.clear();
+  }
+}
+
+/**
+ * Checks if SharedArrayBuffer is available (requires COOP/COEP headers).
+ */
+export function supportsSharedArrayBuffer(): boolean {
+  return typeof SharedArrayBuffer !== "undefined";
+}
+
+/**
+ * Checks if nested Web Workers are supported (creating a Worker from within
+ * another Worker). Not every worker host allows this.
+ */
+export function supportsNestedWorkers(): boolean {
+  try {
+    // We can't fully test without creating a worker, but we can check
+    // that the Worker constructor exists in the current context.
+    return typeof Worker !== "undefined";
+  } catch {
+    return false;
+  }
+}

package/core/src/physics/realm.ts

@@ -0,0 +1,189 @@
+import type { Entity } from "../ecs/entity";
+import type { BodyDesc, BodyType, CharacterControllerDesc, CharacterControllerHandle, CharacterMoveResult, ColliderDesc, ContactManifold, IntersectionPair, IslandInfo, JointDesc, PhysicsBackend, PhysicsBody, PhysicsRealmConfig, RaycastResult } from "./interface";
+
+export class PhysicsRealm {
+  readonly id: number;
+  readonly name: string;
+  readonly tier: import("./interface").RealmTier;
+  private backend: PhysicsBackend;
+  private bodies: Map<number, PhysicsBody> = new Map();
+  private nextBodyId = 1;
+
+  constructor(backend: PhysicsBackend, config: Omit<PhysicsRealmConfig, "id"> & { id?: number }) {
+    this.backend = backend;
+    this.id = config.id ?? Math.floor(Math.random() * 0x7fffffff);
+    this.name = config.name;
+    this.tier = config.tier;
+    this.backend.createRealm({ ...config, id: this.id });
+  }
+
+  createBody(desc: BodyDesc, entity: Entity): PhysicsBody {
+    const body = this.backend.createBody(this.id, desc, entity);
+    this.bodies.set(body.id, body);
+    return body;
+  }
+
+  destroyBody(body: PhysicsBody): void {
+    this.backend.destroyBody(body);
+    this.bodies.delete(body.id);
+  }
+
+  addCollider(body: PhysicsBody, desc: ColliderDesc): number {
+    return this.backend.addCollider(body, desc);
+  }
+
+  removeCollider(body: PhysicsBody, colliderId: number): void {
+    this.backend.removeCollider(body, colliderId);
+  }
+
+  setBodyType(body: PhysicsBody, type: BodyType): void {
+    this.backend.setBodyType(body, type);
+  }
+
+  setPosition(body: PhysicsBody, pos: [number, number, number]): void {
+    this.backend.setPosition(body, pos);
+  }
+
+  getPosition(body: PhysicsBody): [number, number, number] {
+    return this.backend.getPosition(body);
+  }
+
+  setRotation(body: PhysicsBody, rot: [number, number, number, number]): void {
+    this.backend.setRotation(body, rot);
+  }
+
+  getRotation(body: PhysicsBody): [number, number, number, number] {
+    return this.backend.getRotation(body);
+  }
+
+  setLinearVelocity(body: PhysicsBody, vel: [number, number, number]): void {
+    this.backend.setLinearVelocity(body, vel);
+  }
+
+  getLinearVelocity(body: PhysicsBody): [number, number, number] {
+    return this.backend.getLinearVelocity(body);
+  }
+
+  setAngularVelocity(body: PhysicsBody, vel: [number, number, number]): void {
+    this.backend.setAngularVelocity(body, vel);
+  }
+
+  getAngularVelocity(body: PhysicsBody): [number, number, number] {
+    return this.backend.getAngularVelocity(body);
+  }
+
+  applyForce(body: PhysicsBody, force: [number, number, number]): void {
+    this.backend.applyForce(body, force);
+  }
+
+  applyImpulse(body: PhysicsBody, impulse: [number, number, number]): void {
+    this.backend.applyImpulse(body, impulse);
+  }
+
+  raycast(
+    origin: [number, number, number],
+    direction: [number, number, number],
+    maxDistance: number,
+    filter?: { collisionGroups?: number; excludeEntity?: Entity },
+  ): RaycastResult | null {
+    return this.backend.raycast(this.id, origin, direction, maxDistance, filter);
+  }
+
+  raycastMulti(
+    origin: [number, number, number],
+    direction: [number, number, number],
+    maxDistance: number,
+    filter?: { collisionGroups?: number; excludeEntity?: Entity },
+  ): RaycastResult[] {
+    return this.backend.raycastMulti(this.id, origin, direction, maxDistance, filter);
+  }
+
+  step(dt: number): void {
+    this.backend.step(this.id, dt);
+  }
+
+  setSolverIterations(iterations: number): void {
+    this.backend.setSolverIterations(this.id, iterations);
+  }
+
+  setMinIslandSize(size: number): void {
+    if (this.backend.setMinIslandSize) this.backend.setMinIslandSize(this.id, size);
+  }
+
+  setSleepThresholds(linearThreshold: number, angularThreshold: number): void {
+    this.backend.setSleepThresholds(this.id, linearThreshold, angularThreshold);
+  }
+
+  getIslands(): IslandInfo[] {
+    return this.backend.getIslands(this.id);
+  }
+
+  serialize(): Uint8Array {
+    return this.backend.serializeRealm(this.id);
+  }
+
+  deserialize(data: Uint8Array): void {
+    this.backend.deserializeRealm(this.id, data);
+  }
+
+  getContacts(): ContactManifold[] {
+    return this.backend.getContacts(this.id);
+  }
+
+  getIntersections(): IntersectionPair[] {
+    return this.backend.getIntersections(this.id);
+  }
+
+  createCharacterController(desc: CharacterControllerDesc, entity: Entity): CharacterControllerHandle {
+    return this.backend.createCharacterController(this.id, desc, entity);
+  }
+
+  destroyCharacterController(handle: CharacterControllerHandle): void {
+    this.backend.destroyCharacterController(handle);
+  }
+
+  characterMove(handle: CharacterControllerHandle, desiredMovement: [number, number, number], dt: number): CharacterMoveResult {
+    return this.backend.characterMove(handle, desiredMovement, dt);
+  }
+
+  createJoint(parentBody: PhysicsBody, childBody: PhysicsBody, desc: JointDesc): number {
+    return this.backend.createJoint(this.id, parentBody, childBody, desc);
+  }
+
+  destroyJoint(jointId: number): void {
+    this.backend.destroyJoint(this.id, jointId);
+  }
+
+  syncTransforms(transformBuffer: Float32Array, entityCount: number): void {
+    this.backend.syncTransforms(this.id, transformBuffer, entityCount);
+  }
+
+  readTransforms(transformBuffer: Float32Array, entityCount: number): void {
+    this.backend.readTransforms(this.id, transformBuffer, entityCount);
+  }
+
+  listBodies(): PhysicsBody[] {
+    return [...this.bodies.values()];
+  }
+
+  getBody(bodyId: number): PhysicsBody | undefined {
+    return this.bodies.get(bodyId);
+  }
+
+  getBodyCount(): number {
+    return this.bodies.size;
+  }
+
+  getBackend(): PhysicsBackend {
+    return this.backend;
+  }
+
+  getTier(): import("./interface").RealmTier {
+    return this.tier;
+  }
+
+  destroy(): void {
+    this.bodies.clear();
+    this.backend.destroyRealm(this.id);
+  }
+}

package/core/src/physics/registry.ts

@@ -0,0 +1,52 @@
+import type { PhysicsBackend } from "./interface";
+
+class PhysicsBackendRegistry {
+  private backends: Map<string, PhysicsBackend> = new Map();
+  private defaultBackend: PhysicsBackend | null = null;
+
+  register(name: string, backend: PhysicsBackend): void {
+    this.backends.set(name, backend);
+    if (!this.defaultBackend) {
+      this.defaultBackend = backend;
+    }
+  }
+
+  unregister(name: string): void {
+    const backend = this.backends.get(name);
+    if (backend) {
+      backend.destroy();
+      this.backends.delete(name);
+      if (this.defaultBackend === backend) {
+        this.defaultBackend = this.backends.values().next().value ?? null;
+      }
+    }
+  }
+
+  get(name: string): PhysicsBackend | undefined {
+    return this.backends.get(name);
+  }
+
+  getDefault(): PhysicsBackend | null {
+    return this.defaultBackend;
+  }
+
+  setDefault(name: string): void {
+    const backend = this.backends.get(name);
+    if (!backend) throw new Error(`Physics backend "${name}" not registered`);
+    this.defaultBackend = backend;
+  }
+
+  list(): string[] {
+    return [...this.backends.keys()];
+  }
+
+  destroyAll(): void {
+    for (const backend of this.backends.values()) {
+      backend.destroy();
+    }
+    this.backends.clear();
+    this.defaultBackend = null;
+  }
+}
+
+export const physicsBackendRegistry = new PhysicsBackendRegistry();