@downdraft/engine 0.1.1 → 0.2.0

package/dist/core/src/particles/system.js

@@ -0,0 +1,157 @@
+import { ParticleComputePass } from "./compute-pass.js";
+import { ParticleRenderPass } from "./render-pass.js";
+import { ParticleSimulator } from "./simulator.js";
+export const DEFAULT_PARTICLE_CONFIG = {
+    maxParticlesPerEmitter: 10000,
+    useGPUCompute: true,
+    surfaceFormat: "rgba16float",
+};
+let nextEmitterId = 0;
+const MAX_EMITTER_ID = 0x7fffffff;
+export class ParticleSystem {
+    simulator;
+    renderPass = null;
+    computePasses = new Map();
+    emitters = new Map();
+    config;
+    device = null;
+    constructor(config = {}) {
+        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],
+        }, {
+            maxParticlesPerEmitter: this.config.maxParticlesPerEmitter,
+        });
+    }
+    prepare(device) {
+        this.device = device;
+        this.renderPass = new ParticleRenderPass(this.config.surfaceFormat, this.config.maxParticlesPerEmitter);
+        this.renderPass.prepare(device);
+    }
+    registerEmitter(emitterData) {
+        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) {
+        this.emitters.delete(id);
+        const compute = this.computePasses.get(id);
+        if (compute) {
+            compute.destroy();
+            this.computePasses.delete(id);
+        }
+        this.simulator.dispose();
+    }
+    updateEmitter(id, data) {
+        const entry = this.emitters.get(id);
+        if (entry) {
+            entry.data = { ...entry.data, ...data };
+        }
+    }
+    getEmitter(id) {
+        return this.emitters.get(id)?.data;
+    }
+    update(dt) {
+        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, viewProj, cameraPos) {
+        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() {
+        return this.renderPass;
+    }
+    getSimulator() {
+        return this.simulator;
+    }
+    getEmitterCount() {
+        return this.emitters.size;
+    }
+    setTexture(texture) {
+        this.renderPass?.setTexture(texture);
+    }
+    destroy() {
+        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/dist/core/src/physics/body.js

@@ -0,0 +1,25 @@
+import { Component } from "../ecs/component.js";
+export const RigidBody = Component.register("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 const Velocity = Component.register("PhysicsVelocity", {
+    linear: [0, 0, 0],
+    angular: [0, 0, 0],
+});
+export const PhysicsTransform = Component.register("PhysicsTransform", {
+    position: [0, 0, 0],
+    rotation: [0, 0, 0, 1],
+    prevPosition: [0, 0, 0],
+    prevRotation: [0, 0, 0, 1],
+});

package/dist/core/src/physics/ccd-heuristic.js

@@ -0,0 +1,46 @@
+/**
+ * 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). */
+    ccdTunnelingRatio;
+    constructor(opts = {}) {
+        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, colliderSize, dt) {
+        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, bodies, dt, getColliderSize) {
+        bodies.forEach((body) => {
+            const vel = backend.getLinearVelocity(body);
+            const size = getColliderSize(body);
+            const enable = this.shouldEnableCCD(vel, size, dt);
+            backend.setCCDEnabled(body, enable);
+        });
+    }
+}

package/dist/core/src/physics/character.js

@@ -0,0 +1,184 @@
+import { Component } from "../ecs/component.js";
+import { Stage, system } from "../ecs/system.js";
+export const CharacterController = Component.register("CharacterController", {
+    handleRealmId: -1,
+    handleBodyId: -1,
+    controllerHandle: null,
+    radius: 0.4,
+    halfHeight: 0.9,
+    slopeLimit: 0.7,
+    stepHeight: 0.3,
+    maxGroundSpeed: 8,
+    jumpForce: 9.8,
+    airControl: 0.5,
+    autostep: { enabled: true, minWidth: 0.2, maxHeight: 0.3 },
+    maxSlope: Math.PI / 3,
+    minSlopeSlide: Math.PI / 4,
+    snapToGround: 0.1,
+    slide: true,
+    applyImpulsesToDynamicBodies: false,
+    grounded: false,
+    groundNormal: [0, 1, 0],
+    groundEntity: -1,
+    velocity: [0, 0, 0],
+});
+export class CharacterControllerSystem {
+    realm;
+    gravity;
+    world = null;
+    query = null;
+    inputs = new Map();
+    constructor(realm, gravity = [0, -9.81, 0]) {
+        this.realm = realm;
+        this.gravity = gravity;
+    }
+    setRealm(realm) {
+        this.realm = realm;
+    }
+    setInput(entity, position, inputDir, jump) {
+        this.inputs.set(entity.index, { entity, position, inputDir, jump });
+    }
+    clearInput(entity) {
+        this.inputs.delete(entity.index);
+    }
+    createController(entity, controller) {
+        const desc = {
+            // offset[1] is passed to Rapier as the character controller's
+            // artificial gap (a small padding to avoid numerical jitter) — NOT the
+            // capsule radius. A large value inflates the collision shape and freezes
+            // the character against nearby colliders.
+            offset: [0, 0.01, 0],
+            radius: controller.radius,
+            halfHeight: controller.halfHeight,
+            slide: controller.slide,
+            autostep: controller.autostep,
+            maxSlope: controller.maxSlope,
+            minSlopeSlide: controller.minSlopeSlide,
+            snapToGround: controller.snapToGround,
+            applyImpulsesToDynamicBodies: controller.applyImpulsesToDynamicBodies,
+        };
+        const handle = this.realm.createCharacterController(desc, entity);
+        controller.controllerHandle = handle;
+        return handle;
+    }
+    destroyController(controller) {
+        if (controller.controllerHandle) {
+            this.realm.destroyCharacterController(controller.controllerHandle);
+            controller.controllerHandle = null;
+        }
+    }
+    update(controller, position, inputDir, jump, dt) {
+        if (controller.controllerHandle) {
+            return this.updateWithBackend(controller, position, inputDir, jump, dt);
+        }
+        return this.updateWithRaycast(controller, position, inputDir, jump, dt);
+    }
+    updateWithBackend(controller, position, inputDir, jump, dt) {
+        const speed = controller.maxGroundSpeed;
+        const controlFactor = controller.grounded ? 1 : controller.airControl;
+        const desiredHorizontal = [
+            inputDir[0] * speed * controlFactor,
+            0,
+            inputDir[2] * speed * controlFactor,
+        ];
+        let verticalVel = controller.velocity[1];
+        if (controller.grounded) {
+            verticalVel = jump ? controller.jumpForce : 0;
+        }
+        else {
+            verticalVel += this.gravity[1] * dt;
+        }
+        const desiredMovement = [
+            desiredHorizontal[0] * dt,
+            verticalVel * dt,
+            desiredHorizontal[2] * dt,
+        ];
+        const result = this.realm.characterMove(controller.controllerHandle, desiredMovement, dt);
+        controller.grounded = result.grounded;
+        controller.groundNormal = result.groundNormal;
+        controller.groundEntity = result.groundEntity?.index ?? -1;
+        const effectiveSpeed = dt > 1e-6 ? 1 / dt : 0;
+        controller.velocity = [
+            result.effectiveMovement[0] * effectiveSpeed,
+            verticalVel,
+            result.effectiveMovement[2] * effectiveSpeed,
+        ];
+        return [
+            position[0] + result.effectiveMovement[0],
+            position[1] + result.effectiveMovement[1],
+            position[2] + result.effectiveMovement[2],
+        ];
+    }
+    updateWithRaycast(controller, position, inputDir, jump, dt) {
+        const groundCheckOrigin = [
+            position[0],
+            position[1] - controller.halfHeight - 0.05,
+            position[2],
+        ];
+        const groundHit = this.realm.raycast(groundCheckOrigin, [0, -1, 0], 0.15);
+        controller.grounded = groundHit !== null;
+        if (groundHit) {
+            controller.groundNormal = groundHit.normal;
+            controller.groundEntity = groundHit.entity.index;
+        }
+        else {
+            controller.groundNormal = [0, 1, 0];
+            controller.groundEntity = -1;
+        }
+        const speed = controller.maxGroundSpeed;
+        const controlFactor = controller.grounded ? 1 : controller.airControl;
+        const targetVel = [
+            inputDir[0] * speed * controlFactor,
+            controller.velocity[1],
+            inputDir[2] * speed * controlFactor,
+        ];
+        if (controller.grounded) {
+            if (jump) {
+                targetVel[1] = controller.jumpForce;
+            }
+            else {
+                targetVel[1] = 0;
+            }
+        }
+        else {
+            targetVel[1] = controller.velocity[1] + this.gravity[1] * dt;
+        }
+        const slopeDot = controller.groundNormal[1];
+        if (controller.grounded && slopeDot < controller.slopeLimit) {
+            const slideForce = (1 - slopeDot / controller.slopeLimit) * 5;
+            targetVel[0] += controller.groundNormal[0] * slideForce;
+            targetVel[2] += controller.groundNormal[2] * slideForce;
+        }
+        controller.velocity = targetVel;
+        const newPos = [
+            position[0] + targetVel[0] * dt,
+            position[1] + targetVel[1] * dt,
+            position[2] + targetVel[2] * dt,
+        ];
+        return newPos;
+    }
+    checkWallCollision(position, moveDir, maxDist) {
+        return this.realm.raycast([position[0], position[1], position[2]], [moveDir[0], 0, moveDir[2]], maxDist);
+    }
+    register(world, query) {
+        this.world = world;
+        this.query = query;
+        const self = this;
+        const charSystem = system("character-controller", Stage.Physics, (ctx) => {
+            if (!self.query)
+                return;
+            self.query.iterate(ctx.tick, (entity, components) => {
+                const controller = components[0];
+                const input = self.inputs.get(entity.index);
+                if (!input)
+                    return;
+                const newPos = self.update(controller, input.position, input.inputDir, input.jump, ctx.dt);
+                input.position = newPos;
+                if (!input.jump) {
+                    self.inputs.delete(entity.index);
+                }
+            });
+        }, { queries: [query] });
+        world.schedule.add(charSystem);
+    }
+}

package/dist/core/src/physics/collider.js

@@ -0,0 +1,36 @@
+import { Component } from "../ecs/component.js";
+export const Collider = Component.register("Collider", {
+    shape: { type: "box", halfExtents: [0.5, 0.5, 0.5] },
+    friction: 0.5,
+    restitution: 0.0,
+    density: 1.0,
+    sensor: false,
+    collisionGroups: 0xffffffff,
+    solverGroups: 0xffffffff,
+    colliderId: -1,
+});
+export function createBoxCollider(halfExtents) {
+    return Collider.create({
+        shape: { type: "box", halfExtents },
+    });
+}
+export function createSphereCollider(radius) {
+    return Collider.create({
+        shape: { type: "sphere", radius },
+    });
+}
+export function createCapsuleCollider(halfHeight, radius) {
+    return Collider.create({
+        shape: { type: "capsule", halfHeight, radius },
+    });
+}
+export function createMeshCollider(vertices, indices) {
+    return Collider.create({
+        shape: { type: "mesh", vertices, indices },
+    });
+}
+export function createConvexCollider(vertices) {
+    return Collider.create({
+        shape: { type: "convex", vertices },
+    });
+}

package/dist/core/src/physics/collision-system.js

@@ -0,0 +1,62 @@
+import { Stage, system } from "../ecs/system.js";
+import { COLLISION_STARTED_CHANNEL, COLLISION_STOPPED_CHANNEL, computeCollisionEvents, computeTriggerEvents, CONTACT_CHANNEL, TRIGGER_ENTER_CHANNEL, TRIGGER_EXIT_CHANNEL, } from "./events.js";
+export class CollisionEventSystem {
+    realm;
+    world;
+    previousContacts = [];
+    previousIntersections = [];
+    constructor(world, realm) {
+        this.world = world;
+        this.realm = realm;
+    }
+    setRealm(realm) {
+        this.realm = realm;
+        this.previousContacts = [];
+        this.previousIntersections = [];
+    }
+    update() {
+        const currentContacts = this.realm.getContacts();
+        const { started, stopped, contacts } = computeCollisionEvents(currentContacts, this.previousContacts);
+        const startedChannel = this.world.events.get(COLLISION_STARTED_CHANNEL);
+        const stoppedChannel = this.world.events.get(COLLISION_STOPPED_CHANNEL);
+        const contactChannel = this.world.events.get(CONTACT_CHANNEL);
+        started.forEach((event) => {
+            startedChannel.send(event);
+        });
+        stopped.forEach((event) => {
+            stoppedChannel.send(event);
+        });
+        contacts.forEach((event) => {
+            contactChannel.send(event);
+        });
+        this.previousContacts = currentContacts;
+        // Trigger (sensor) enter/exit events
+        const currentIntersections = this.realm.getIntersections();
+        const { entered, exited } = computeTriggerEvents(currentIntersections, this.previousIntersections);
+        const enterChannel = this.world.events.get(TRIGGER_ENTER_CHANNEL);
+        const exitChannel = this.world.events.get(TRIGGER_EXIT_CHANNEL);
+        entered.forEach((event) => {
+            enterChannel.send(event);
+        });
+        exited.forEach((event) => {
+            exitChannel.send(event);
+        });
+        this.previousIntersections = currentIntersections;
+    }
+    register() {
+        const self = this;
+        const collisionSystem = system("collision-events", Stage.PostUpdate, () => {
+            self.update();
+        });
+        this.world.schedule.add(collisionSystem);
+    }
+    clear() {
+        this.previousContacts = [];
+        this.previousIntersections = [];
+        this.world.events.get(COLLISION_STARTED_CHANNEL).clear();
+        this.world.events.get(COLLISION_STOPPED_CHANNEL).clear();
+        this.world.events.get(CONTACT_CHANNEL).clear();
+        this.world.events.get(TRIGGER_ENTER_CHANNEL).clear();
+        this.world.events.get(TRIGGER_EXIT_CHANNEL).clear();
+    }
+}

package/dist/core/src/physics/events.js

@@ -0,0 +1,74 @@
+export const COLLISION_STARTED_CHANNEL = "physics:collision_started";
+export const COLLISION_STOPPED_CHANNEL = "physics:collision_stopped";
+export const CONTACT_CHANNEL = "physics:contact";
+export const TRIGGER_ENTER_CHANNEL = "physics:trigger_enter";
+export const TRIGGER_EXIT_CHANNEL = "physics:trigger_exit";
+export function manifoldToStartedEvent(manifold) {
+    return {
+        entityA: manifold.entityA,
+        entityB: manifold.entityB,
+        normal: manifold.normal,
+        penetrationDepth: manifold.penetrationDepth,
+        contactPoints: manifold.points,
+    };
+}
+export function computeCollisionEvents(currentContacts, previousContacts) {
+    const started = [];
+    const stopped = [];
+    const contacts = [];
+    const prevPairs = new Set();
+    previousContacts.forEach((m) => {
+        const key = pairKey(m.entityA, m.entityB);
+        prevPairs.add(key);
+    });
+    const currPairs = new Set();
+    currentContacts.forEach((m) => {
+        const key = pairKey(m.entityA, m.entityB);
+        currPairs.add(key);
+        contacts.push({
+            entityA: m.entityA,
+            entityB: m.entityB,
+            normal: m.normal,
+            penetrationDepth: m.penetrationDepth,
+            contactPoints: m.points,
+        });
+        if (!prevPairs.has(key)) {
+            started.push(manifoldToStartedEvent(m));
+        }
+    });
+    previousContacts.forEach((m) => {
+        const key = pairKey(m.entityA, m.entityB);
+        if (!currPairs.has(key)) {
+            stopped.push({ entityA: m.entityA, entityB: m.entityB });
+        }
+    });
+    return { started, stopped, contacts };
+}
+export function computeTriggerEvents(currentIntersections, previousIntersections) {
+    const entered = [];
+    const exited = [];
+    const prevPairs = new Set();
+    previousIntersections.forEach((p) => {
+        prevPairs.add(pairKey(p.entityA, p.entityB));
+    });
+    const currPairs = new Set();
+    currentIntersections.forEach((p) => {
+        const key = pairKey(p.entityA, p.entityB);
+        currPairs.add(key);
+        if (!prevPairs.has(key)) {
+            entered.push({ entityA: p.entityA, entityB: p.entityB });
+        }
+    });
+    previousIntersections.forEach((p) => {
+        const key = pairKey(p.entityA, p.entityB);
+        if (!currPairs.has(key)) {
+            exited.push({ entityA: p.entityA, entityB: p.entityB });
+        }
+    });
+    return { entered, exited };
+}
+function pairKey(a, b) {
+    const i1 = a.index < b.index ? a : b;
+    const i2 = a.index < b.index ? b : a;
+    return `${i1.index}:${i1.generation}-${i2.index}:${i2.generation}`;
+}

package/dist/core/src/physics/index.js

@@ -0,0 +1,24 @@
+// Physics sub-barrel — re-exports all physics-related items.
+export { PhysicsTransform, RigidBody, Velocity } from "./body.js";
+export { CCDHeuristic } from "./ccd-heuristic.js";
+export { CharacterController, CharacterControllerSystem } from "./character.js";
+export { Collider, createBoxCollider, createCapsuleCollider, createConvexCollider, createMeshCollider, createSphereCollider } from "./collider.js";
+export { CollisionEventSystem } from "./collision-system.js";
+export { COLLISION_STARTED_CHANNEL, COLLISION_STOPPED_CHANNEL, computeCollisionEvents, computeTriggerEvents, CONTACT_CHANNEL, manifoldToStartedEvent, TRIGGER_ENTER_CHANNEL, TRIGGER_EXIT_CHANNEL } from "./events.js";
+export { RealmTier } from "./interface.js";
+export { InterpolationBuffer } from "./interpolation-buffer.js";
+export { PhysicsLifecycle } from "./lifecycle.js";
+export { LoadShedder } from "./load-shedder.js";
+export { PhysicsAccumulator } from "./physics-accumulator.js";
+export { createPhysicsSystem } from "./physics-system.js";
+export { createRagdoll, destroyRagdoll, Ragdoll } from "./ragdoll.js";
+export { humanoidRagdoll } from "./ragdoll-presets.js";
+export { RagdollSystem } from "./ragdoll-system.js";
+export { RaycastQuery } from "./raycast.js";
+export { PhysicsRealm } from "./realm.js";
+export { RealmManager } from "./realm-manager.js";
+export { RealmWorker, supportsNestedWorkers, supportsSharedArrayBuffer } from "./realm-worker.js";
+export { RealmWorkerPool } from "./realm-worker-pool.js";
+export { physicsBackendRegistry } from "./registry.js";
+export { SafetyLayer } from "./safety.js";
+export { SnapshotManager } from "./snapshot-manager.js";

package/dist/core/src/physics/interface.js

@@ -0,0 +1,14 @@
+// ---------------------------------------------------------------------------
+// Realm tiers
+// ---------------------------------------------------------------------------
+/**
+ * Realm tier enum. Lower numeric value = higher fidelity (more frequent ticks,
+ * more solver iterations). Realm separation is the only mechanism for differing
+ * per-body update frequencies within Rapier (a single `World` has one tick rate).
+ */
+export var RealmTier;
+(function (RealmTier) {
+    RealmTier[RealmTier["Near"] = 0] = "Near";
+    RealmTier[RealmTier["Mid"] = 1] = "Mid";
+    RealmTier[RealmTier["Far"] = 2] = "Far";
+})(RealmTier || (RealmTier = {}));