@downdraft/engine 0.0.0 → 0.1.0

package/core/src/particles/simulator.ts

@@ -0,0 +1,264 @@
+import type { EmitterShapeData, ParticleEmitterData } from "./emitter";
+import type { ParticleGPUData } from "./particle-data";
+
+const TWO_PI = Math.PI * 2;
+
+function rand(): number {
+  return Math.random();
+}
+
+function randRange(min: number, max: number): number {
+  return min + rand() * (max - min);
+}
+
+function sampleShape(shape: EmitterShapeData | string, size: [number, number, number]): [number, number, number] {
+  const [sx, sy, sz] = size;
+  const type = typeof shape === "string" ? shape : shape?.type ?? "point";
+  switch (type) {
+    case "point":
+      return [0, 0, 0];
+    case "sphere": {
+      const theta = rand() * TWO_PI;
+      const phi = Math.acos(rand() * 2 - 1);
+      const r = sx * Math.cbrt(rand());
+      return [
+        r * Math.sin(phi) * Math.cos(theta),
+        r * Math.sin(phi) * Math.sin(theta),
+        r * Math.cos(phi),
+      ];
+    }
+    case "box":
+      return [randRange(-sx, sx), randRange(-sy, sy), randRange(-sz, sz)];
+    case "cone": {
+      const angle = rand() * TWO_PI;
+      const r = sx * Math.sqrt(rand());
+      return [r * Math.cos(angle), 0, r * Math.sin(angle)];
+    }
+    case "disc": {
+      const angle = rand() * TWO_PI;
+      const r = sx * Math.sqrt(rand());
+      return [r * Math.cos(angle), 0, r * Math.sin(angle)];
+    }
+    default:
+      return [0, 0, 0];
+  }
+}
+
+function normalize(v: [number, number, number]): [number, number, number] {
+  const len = Math.sqrt(v[0] * v[0] + v[1] * v[1] + v[2] * v[2]);
+  if (len < 1e-9) return [0, 1, 0];
+  return [v[0] / len, v[1] / len, v[2] / len];
+}
+
+function cross(a: [number, number, number], b: [number, number, number]): [number, number, number] {
+  return [
+    a[1] * b[2] - a[2] * b[1],
+    a[2] * b[0] - a[0] * b[2],
+    a[0] * b[1] - a[1] * b[0],
+  ];
+}
+
+function sampleConeDirection(dir: [number, number, number], angle: number): [number, number, number] {
+  const n = normalize(dir);
+  // Find an arbitrary perpendicular
+  const up: [number, number, number] = Math.abs(n[1]) < 0.99 ? [0, 1, 0] : [1, 0, 0];
+  const tangent = normalize(cross(up, n));
+  const bitangent = cross(n, tangent);
+
+  const cosAngle = Math.cos(angle);
+  const phi = rand() * TWO_PI;
+  const theta = Math.acos(randRange(cosAngle, 1));
+
+  const sinTheta = Math.sin(theta);
+  const cosTheta = Math.cos(theta);
+  const sinPhi = Math.sin(phi);
+  const cosPhi = Math.cos(phi);
+
+  return [
+    n[0] * cosTheta + tangent[0] * sinTheta * cosPhi + bitangent[0] * sinTheta * sinPhi,
+    n[1] * cosTheta + tangent[1] * sinTheta * cosPhi + bitangent[1] * sinTheta * sinPhi,
+    n[2] * cosTheta + tangent[2] * sinTheta * cosPhi + bitangent[2] * sinTheta * sinPhi,
+  ];
+}
+
+export interface ParticleSimulatorConfig {
+  maxParticlesPerEmitter: number;
+}
+
+export class ParticleSimulator {
+  private emitter: ParticleEmitterData;
+  private gpuData: ParticleGPUData;
+  private cursor: number = 0;
+  private config: ParticleSimulatorConfig;
+
+  constructor(emitter: ParticleEmitterData, config: Partial<ParticleSimulatorConfig> = {}) {
+    this.emitter = emitter;
+    this.config = {
+      maxParticlesPerEmitter: config.maxParticlesPerEmitter ?? 10000,
+    };
+    const capped = Math.min(emitter.maxParticles, this.config.maxParticlesPerEmitter);
+    this.gpuData = this._createData(capped);
+  }
+
+  private _createData(max: number): ParticleGPUData {
+    return {
+      position: new Float32Array(max * 3),
+      velocity: new Float32Array(max * 3),
+      color: new Float32Array(max * 4),
+      size: new Float32Array(max),
+      lifetime: new Float32Array(max),
+      maxLifetime: new Float32Array(max),
+      rotation: new Float32Array(max),
+      angularVelocity: new Float32Array(max),
+      active: new Uint8Array(max),
+    };
+  }
+
+  getParticleData(): ParticleGPUData {
+    return this.gpuData;
+  }
+
+  update(dt: number): ParticleGPUData {
+    const emitter = this.emitter;
+    const data = this.gpuData;
+    const max = Math.min(emitter.maxParticles, this.config.maxParticlesPerEmitter);
+    let cursor = this.cursor;
+
+    // Emit new particles
+    if (emitter.active) {
+      const toEmit = Math.min(
+        Math.ceil(emitter.emissionRate * dt),
+        max - this._countActive(data, max),
+      );
+
+      for (let i = 0; i < toEmit; i++) {
+        const offset = sampleShape(emitter.shape, emitter.shapeSize ?? emitter.shape?.size ?? [0, 0, 0]);
+        const px = emitter.position[0] + offset[0];
+        const py = emitter.position[1] + offset[1];
+        const pz = emitter.position[2] + offset[2];
+
+        let dir: [number, number, number];
+        const shapeType = typeof emitter.shape === "string" ? emitter.shape : emitter.shape?.type ?? "point";
+        if (shapeType === "cone") {
+          const coneAngle = Math.PI / 6;
+          dir = sampleConeDirection(emitter.direction, coneAngle);
+        } else if (shapeType === "sphere") {
+          dir = normalize([offset[0], offset[1], offset[2]]);
+        } else {
+          dir = normalize(emitter.direction);
+          dir = [
+            dir[0] + randRange(-0.2, 0.2),
+            dir[1] + randRange(-0.2, 0.2),
+            dir[2] + randRange(-0.2, 0.2),
+          ];
+          dir = normalize(dir);
+        }
+
+        const speed = emitter.speed + randRange(-emitter.speedVariance, emitter.speedVariance);
+        const life = emitter.lifetime + randRange(-emitter.lifetimeVariance, emitter.lifetimeVariance);
+        const sz = emitter.startSize + randRange(-emitter.sizeVariance, emitter.sizeVariance);
+        const angVel = emitter.angularVelocity + randRange(-emitter.angularVelocityVariance, emitter.angularVelocityVariance);
+
+        const idx = cursor;
+        data.position[idx * 3 + 0] = px;
+        data.position[idx * 3 + 1] = py;
+        data.position[idx * 3 + 2] = pz;
+        data.velocity[idx * 3 + 0] = dir[0] * speed;
+        data.velocity[idx * 3 + 1] = dir[1] * speed;
+        data.velocity[idx * 3 + 2] = dir[2] * speed;
+        data.color[idx * 4 + 0] = emitter.startColor[0];
+        data.color[idx * 4 + 1] = emitter.startColor[1];
+        data.color[idx * 4 + 2] = emitter.startColor[2];
+        data.color[idx * 4 + 3] = emitter.startColor[3];
+        data.size[idx] = sz;
+        data.lifetime[idx] = life;
+        data.maxLifetime[idx] = life;
+        data.rotation[idx] = rand() * TWO_PI;
+        data.angularVelocity[idx] = angVel;
+        data.active[idx] = 1;
+
+        cursor = (cursor + 1) % max;
+      }
+
+      this.cursor = cursor;
+    }
+
+    // Update existing particles
+    const dragFactor = Math.exp(-emitter.drag * dt);
+    const gx = emitter.gravity[0] * dt;
+    const gy = emitter.gravity[1] * dt;
+    const gz = emitter.gravity[2] * dt;
+
+    for (let i = 0; i < max; i++) {
+      if (!data.active[i]) continue;
+
+      // Apply gravity
+      data.velocity[i * 3 + 0] += gx;
+      data.velocity[i * 3 + 1] += gy;
+      data.velocity[i * 3 + 2] += gz;
+
+      // Apply drag
+      data.velocity[i * 3 + 0] *= dragFactor;
+      data.velocity[i * 3 + 1] *= dragFactor;
+      data.velocity[i * 3 + 2] *= dragFactor;
+
+      // Update position
+      data.position[i * 3 + 0] += data.velocity[i * 3 + 0] * dt;
+      data.position[i * 3 + 1] += data.velocity[i * 3 + 1] * dt;
+      data.position[i * 3 + 2] += data.velocity[i * 3 + 2] * dt;
+
+      // Update rotation
+      data.rotation[i] += data.angularVelocity[i] * dt;
+
+      // Decrease lifetime
+      data.lifetime[i] -= dt;
+      if (data.lifetime[i] <= 0) {
+        data.active[i] = 0;
+        continue;
+      }
+
+      // Interpolate color and size
+      const maxLife = data.maxLifetime[i];
+      if (maxLife <= 0) continue;
+      const t = 1 - data.lifetime[i] / maxLife; // 0=birth, 1=death
+      data.color[i * 4 + 0] = emitter.startColor[0] + (emitter.endColor[0] - emitter.startColor[0]) * t;
+      data.color[i * 4 + 1] = emitter.startColor[1] + (emitter.endColor[1] - emitter.startColor[1]) * t;
+      data.color[i * 4 + 2] = emitter.startColor[2] + (emitter.endColor[2] - emitter.startColor[2]) * t;
+      data.color[i * 4 + 3] = emitter.startColor[3] + (emitter.endColor[3] - emitter.startColor[3]) * t;
+      data.size[i] = emitter.startSize + (emitter.endSize - emitter.startSize) * t;
+    }
+
+    return data;
+  }
+
+  simulate(emitterId: number, emitter: ParticleEmitterData, dt: number): ParticleGPUData {
+    return this.update(dt);
+  }
+
+  private _countActive(data: ParticleGPUData, max: number): number {
+    let count = 0;
+    for (let i = 0; i < max; i++) {
+      if (data.active[i]) count++;
+    }
+    return count;
+  }
+
+  getActiveCount(data: ParticleGPUData, max: number): number {
+    return this._countActive(data, max);
+  }
+
+  reset(): void {
+    this.gpuData.active.fill(0);
+    this.gpuData.lifetime.fill(0);
+    this.cursor = 0;
+  }
+
+  dispose(): void {
+    this.gpuData = this._createData(0);
+    this.cursor = 0;
+  }
+
+  disposeAll(): void {
+    this.reset();
+  }
+}

package/core/src/particles/system.ts

@@ -0,0 +1,193 @@
+import { type Mat4 } from "wgpu-matrix";
+import type { GraphRenderContext } from "../index";
+import { ParticleComputePass } from "./compute-pass";
+import type { ParticleEmitterData } from "./emitter";
+import type { ParticleGPUData } from "./particle-data";
+import { ParticleRenderPass } from "./render-pass";
+import { ParticleSimulator } from "./simulator";
+
+export interface ParticleSystemConfig {
+  maxParticlesPerEmitter: number;
+  useGPUCompute: boolean;
+  surfaceFormat: GPUTextureFormat;
+}
+
+export const DEFAULT_PARTICLE_CONFIG: ParticleSystemConfig = {
+  maxParticlesPerEmitter: 10000,
+  useGPUCompute: true,
+  surfaceFormat: "rgba16float",
+};
+
+interface EmitterEntry {
+  id: number;
+  data: ParticleEmitterData;
+  gpuData?: ParticleGPUData;
+  computePass?: ParticleComputePass;
+}
+
+let nextEmitterId = 0;
+const MAX_EMITTER_ID = 0x7fffffff;
+
+export class ParticleSystem {
+  private simulator: ParticleSimulator;
+  private renderPass: ParticleRenderPass | null = null;
+  private computePasses: Map<number, ParticleComputePass> = new Map();
+  private emitters: Map<number, EmitterEntry> = new Map();
+  private config: ParticleSystemConfig;
+  private device: GPUDevice | null = null;
+
+  constructor(config: Partial<ParticleSystemConfig> = {}) {
+    this.config = { ...DEFAULT_PARTICLE_CONFIG, ...config };
+    this.simulator = new ParticleSimulator({
+      maxParticles: this.config.maxParticlesPerEmitter,
+      shape: "point",
+      rate: 0,
+      lifetime: 1,
+      speed: 1,
+      size: 1,
+      color: [1, 1, 1, 1],
+    } as any, {
+      maxParticlesPerEmitter: this.config.maxParticlesPerEmitter,
+    });
+  }
+
+  prepare(device: GPUDevice): void {
+    this.device = device;
+    this.renderPass = new ParticleRenderPass(this.config.surfaceFormat, this.config.maxParticlesPerEmitter);
+    this.renderPass.prepare(device);
+  }
+
+  registerEmitter(emitterData: ParticleEmitterData): number {
+    const id = nextEmitterId;
+    nextEmitterId = (nextEmitterId + 1) % MAX_EMITTER_ID;
+    this.emitters.set(id, { id, data: emitterData });
+
+    if (this.config.useGPUCompute && this.device) {
+      const compute = new ParticleComputePass(emitterData.maxParticles);
+      compute.prepare(this.device);
+      this.computePasses.set(id, compute);
+    }
+
+    return id;
+  }
+
+  unregisterEmitter(id: number): void {
+    this.emitters.delete(id);
+    const compute = this.computePasses.get(id);
+    if (compute) {
+      compute.destroy();
+      this.computePasses.delete(id);
+    }
+    this.simulator.dispose();
+  }
+
+  updateEmitter(id: number, data: Partial<ParticleEmitterData>): void {
+    const entry = this.emitters.get(id);
+    if (entry) {
+      entry.data = { ...entry.data, ...data };
+    }
+  }
+
+  getEmitter(id: number): ParticleEmitterData | undefined {
+    return this.emitters.get(id)?.data;
+  }
+
+  update(dt: number): void {
+    for (const [id, entry] of this.emitters.entries()) {
+      if (!entry.data.active) continue;
+
+      if (this.config.useGPUCompute && this.device) {
+        const compute = this.computePasses.get(id);
+        if (compute) {
+          compute.emit({
+            deltaTime: dt,
+            emissionRate: entry.data.emissionRate,
+            speed: entry.data.speed,
+            speedVariance: entry.data.speedVariance,
+            lifetime: entry.data.lifetime,
+            lifetimeVariance: entry.data.lifetimeVariance,
+            startSize: entry.data.startSize,
+            sizeVariance: entry.data.sizeVariance,
+            startColor: entry.data.startColor,
+            emitterPos: entry.data.position,
+            emitterDir: entry.data.direction,
+          });
+
+          compute.update({
+            deltaTime: dt,
+            gravity: entry.data.gravity,
+            drag: entry.data.drag,
+            maxParticles: entry.data.maxParticles,
+            emissionRate: entry.data.emissionRate,
+            speed: entry.data.speed,
+            speedVariance: entry.data.speedVariance,
+            lifetime: entry.data.lifetime,
+            lifetimeVariance: entry.data.lifetimeVariance,
+            startSize: entry.data.startSize,
+            endSize: entry.data.endSize,
+            sizeVariance: entry.data.sizeVariance,
+            startColor: entry.data.startColor,
+            endColor: entry.data.endColor,
+            angularVelocity: entry.data.angularVelocity,
+            angularVelocityVariance: entry.data.angularVelocityVariance,
+            emitterPos: entry.data.position,
+            emitterDir: entry.data.direction,
+          });
+        }
+      } else {
+        // CPU simulation fallback
+        entry.gpuData = this.simulator.simulate(id, entry.data, dt);
+      }
+
+      entry.data.elapsed += dt;
+    }
+  }
+
+  render(ctx: GraphRenderContext, viewProj: Mat4, cameraPos: [number, number, number]): void {
+    if (!this.renderPass) return;
+
+    this.renderPass.setCamera(viewProj, cameraPos);
+
+    for (const [, entry] of this.emitters.entries()) {
+      if (this.config.useGPUCompute) {
+        // GPU compute path: render directly from compute buffer
+        // This requires the render pass to read from the compute buffer
+        // For now, we use the CPU fallback data for rendering
+        if (entry.gpuData) {
+          this.renderPass.renderInstances(ctx, entry.gpuData, entry.data.maxParticles);
+        }
+      } else {
+        if (entry.gpuData) {
+          this.renderPass.renderInstances(ctx, entry.gpuData, entry.data.maxParticles);
+        }
+      }
+    }
+  }
+
+  getRenderPass(): ParticleRenderPass | null {
+    return this.renderPass;
+  }
+
+  getSimulator(): ParticleSimulator {
+    return this.simulator;
+  }
+
+  getEmitterCount(): number {
+    return this.emitters.size;
+  }
+
+  setTexture(texture: GPUTexture): void {
+    this.renderPass?.setTexture(texture);
+  }
+
+  destroy(): void {
+    for (const [, compute] of this.computePasses.entries()) {
+      compute.destroy();
+    }
+    this.computePasses.clear();
+    this.renderPass?.destroy();
+    this.renderPass = null;
+    this.simulator.disposeAll();
+    this.emitters.clear();
+  }
+}

package/core/src/physics/body.ts

@@ -0,0 +1,59 @@
+import { Component } from "../ecs/component";
+import type { BodyType } from "./interface";
+
+export interface RigidBodyData {
+  [key: string]: unknown;
+  bodyType: BodyType;
+  bodyId: number;
+  realmId: number;
+  mass: number;
+  linearDamping: number;
+  angularDamping: number;
+  gravityScale: number;
+  ccdEnabled: boolean;
+  canSleep: boolean;
+  sleeping: boolean;
+  lockedTranslation: [boolean, boolean, boolean] | null;
+  lockedRotation: [boolean, boolean, boolean] | null;
+}
+
+export const RigidBody = Component.register<RigidBodyData>("PhysicsRigidBody", {
+  bodyType: "dynamic",
+  bodyId: -1,
+  realmId: -1,
+  mass: 1,
+  linearDamping: 0.1,
+  angularDamping: 0.1,
+  gravityScale: 1,
+  ccdEnabled: false,
+  canSleep: true,
+  sleeping: false,
+  lockedTranslation: null,
+  lockedRotation: null,
+});
+
+export interface VelocityData {
+  [key: string]: unknown;
+  linear: [number, number, number];
+  angular: [number, number, number];
+}
+
+export const Velocity = Component.register<VelocityData>("PhysicsVelocity", {
+  linear: [0, 0, 0],
+  angular: [0, 0, 0],
+});
+
+export interface PhysicsTransformData {
+  [key: string]: unknown;
+  position: [number, number, number];
+  rotation: [number, number, number, number];
+  prevPosition: [number, number, number];
+  prevRotation: [number, number, number, number];
+}
+
+export const PhysicsTransform = Component.register<PhysicsTransformData>("PhysicsTransform", {
+  position: [0, 0, 0],
+  rotation: [0, 0, 0, 1],
+  prevPosition: [0, 0, 0],
+  prevRotation: [0, 0, 0, 1],
+});

package/core/src/physics/ccd-heuristic.ts

@@ -0,0 +1,55 @@
+import type { PhysicsBackend, PhysicsBody } from "./interface";
+
+/**
+ * Per-object CCD (Continuous Collision Detection) heuristic.
+ *
+ * Tunneling risk = `speed × dt / colliderSize`. If the risk exceeds
+ * `ccdTunnelingRatio` (default 0.5), CCD is enabled for that body.
+ *
+ * This avoids the global CCD cost by only opting in bodies that are
+ * actually at risk of tunneling this tick.
+ */
+export class CCDHeuristic {
+  /** Ratio threshold for enabling CCD (default 0.5). */
+  readonly ccdTunnelingRatio: number;
+
+  constructor(opts: { ccdTunnelingRatio?: number } = {}) {
+    this.ccdTunnelingRatio = opts.ccdTunnelingRatio ?? 0.5;
+  }
+
+  /**
+   * Compute whether CCD should be enabled for a body given its velocity,
+   * collider size, and the fixed timestep.
+   *
+   * `colliderSize` is the smallest dimension of the body's colliders
+   * (e.g. sphere radius, min box half-extent × 2).
+   */
+  shouldEnableCCD(velocity: [number, number, number], colliderSize: number, dt: number): boolean {
+    if (colliderSize <= 0) return false;
+    const speed = Math.sqrt(velocity[0] ** 2 + velocity[1] ** 2 + velocity[2] ** 2);
+    const risk = (speed * dt) / colliderSize;
+    return risk > this.ccdTunnelingRatio;
+  }
+
+  /**
+   * Per-tick update: for each dynamic body, check speed vs collider size
+   * and enable/disable CCD accordingly.
+   *
+   * `getColliderSize(body)` returns the smallest collider dimension for
+   * the body (caller-provided; the backend doesn't expose collider sizes
+   * in a uniform way).
+   */
+  updateCCD(
+    backend: PhysicsBackend,
+    bodies: PhysicsBody[],
+    dt: number,
+    getColliderSize: (body: PhysicsBody) => number,
+  ): void {
+    bodies.forEach((body) => {
+      const vel = backend.getLinearVelocity(body);
+      const size = getColliderSize(body);
+      const enable = this.shouldEnableCCD(vel, size, dt);
+      backend.setCCDEnabled(body, enable);
+    });
+  }
+}