@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/core/src/render/buffer.js

@@ -0,0 +1,74 @@
+export class RingBuffer {
+    buffer = null;
+    capacity;
+    head = 0;
+    alignedSize;
+    device;
+    constructor(device, capacity, alignedSize = 256) {
+        this.device = device;
+        this.capacity = capacity;
+        this.alignedSize = alignedSize;
+        this.buffer = device.createBuffer({
+            size: capacity,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+    }
+    allocate(size) {
+        if (!this.buffer)
+            return null;
+        const aligned = Math.ceil(size / this.alignedSize) * this.alignedSize;
+        if (this.head + aligned > this.capacity) {
+            this.head = 0;
+        }
+        const offset = this.head;
+        this.head += aligned;
+        return { offset, buffer: this.buffer };
+    }
+    write(data, offset = 0) {
+        if (!this.buffer)
+            return;
+        this.device.queue.writeBuffer(this.buffer, offset, data);
+    }
+    reset() {
+        this.head = 0;
+    }
+    destroy() {
+        this.buffer?.destroy();
+        this.buffer = null;
+    }
+}
+export class ArenaBuffer {
+    buffer = null;
+    capacity;
+    offset = 0;
+    device;
+    constructor(device, capacity) {
+        this.device = device;
+        this.capacity = capacity;
+        this.buffer = device.createBuffer({
+            size: capacity,
+            usage: GPUBufferUsage.VERTEX | GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+        });
+    }
+    allocate(size) {
+        const aligned = Math.ceil(size / 4) * 4;
+        if (this.offset + aligned > this.capacity) {
+            this.offset = 0;
+        }
+        const result = this.offset;
+        this.offset += aligned;
+        return result;
+    }
+    write(data, offset) {
+        if (!this.buffer)
+            return;
+        this.device.queue.writeBuffer(this.buffer, offset, data);
+    }
+    reset() {
+        this.offset = 0;
+    }
+    destroy() {
+        this.buffer?.destroy();
+        this.buffer = null;
+    }
+}

package/dist/core/src/render/camera-2d.js

@@ -0,0 +1,151 @@
+// ============================================================================
+// Camera2D — 2D camera for grid-based / cellular automata games
+// ============================================================================
+//
+// Tracks a position in world coordinates with zoom. Provides screen↔world
+// coordinate conversion, smooth lerp follow, and a GPU-ready transform matrix.
+// Used by mining-rpg (player follow + zoom) and falling-sand (GPU matrix).
+/** Create a 2D camera. Defaults to origin-centered with zoom=1. */
+export function makeCamera2D(w, h, opts) {
+    const zoom = opts?.zoom ?? 1;
+    const x = opts?.x ?? w / 2 / zoom;
+    const y = opts?.y ?? h / 2 / zoom;
+    return { x, y, zoom, width: w, height: h };
+}
+/** Smoothly move camera toward a target position via lerp. */
+export function updateCamera(cam, targetX, targetY, smooth = 0.08) {
+    cam.x += (targetX - cam.x) * smooth;
+    cam.y += (targetY - cam.y) * smooth;
+}
+/** Convert screen pixel coords to world coords. */
+export function screenToWorld(cam, sx, sy) {
+    return {
+        x: (sx - cam.width / 2) / cam.zoom + cam.x,
+        y: (sy - cam.height / 2) / cam.zoom + cam.y,
+    };
+}
+/** Convert world coords to screen pixel coords. */
+export function worldToScreen(cam, wx, wy) {
+    return {
+        x: (wx - cam.x) * cam.zoom + cam.width / 2,
+        y: (wy - cam.y) * cam.zoom + cam.height / 2,
+    };
+}
+export class PanZoomCamera2D {
+    // Camera position in world coordinates (center of view)
+    x;
+    y;
+    /** Zoom: pixels per world unit */
+    zoom;
+    /** Canvas dimensions in pixels */
+    canvasW;
+    canvasH;
+    minZoom;
+    maxZoom;
+    // Detached mode: camera doesn't follow the player. When detached, movement
+    // input typically pans the camera instead of moving the player.
+    detached = false;
+    // Pan state (mouse drag)
+    panning = false;
+    panStartX = 0;
+    panStartY = 0;
+    panStartCamX = 0;
+    panStartCamY = 0;
+    constructor(canvasW, canvasH, opts) {
+        this.canvasW = canvasW;
+        this.canvasH = canvasH;
+        this.x = opts?.x ?? 0;
+        this.y = opts?.y ?? 0;
+        this.zoom = opts?.zoom ?? 1;
+        this.minZoom = opts?.minZoom ?? 0;
+        this.maxZoom = opts?.maxZoom ?? Infinity;
+    }
+    resize(w, h) {
+        this.canvasW = w;
+        this.canvasH = h;
+    }
+    setCenter(x, y) {
+        this.x = x;
+        this.y = y;
+    }
+    startPan(screenX, screenY) {
+        this.panning = true;
+        this.panStartX = screenX;
+        this.panStartY = screenY;
+        this.panStartCamX = this.x;
+        this.panStartCamY = this.y;
+    }
+    updatePan(screenX, screenY) {
+        if (!this.panning)
+            return;
+        const dx = (screenX - this.panStartX) / this.zoom;
+        const dy = (screenY - this.panStartY) / this.zoom;
+        this.x = this.panStartCamX - dx;
+        this.y = this.panStartCamY - dy;
+    }
+    endPan() {
+        this.panning = false;
+    }
+    isPanning() {
+        return this.panning;
+    }
+    /** Move the camera by a delta in world coordinates (e.g. WASD in detached mode). */
+    move(dx, dy) {
+        this.x += dx;
+        this.y += dy;
+    }
+    /** Re-center on a position and re-attach to the follow target. */
+    reattach(x, y) {
+        this.x = x;
+        this.y = y;
+        this.detached = false;
+        this.panning = false;
+    }
+    /** Zoom by `factor`, keeping the world point under the cursor fixed. */
+    zoomAt(screenX, screenY, factor) {
+        const oldZoom = this.zoom;
+        const newZoom = Math.max(this.minZoom, Math.min(this.maxZoom, this.zoom * factor));
+        if (newZoom === oldZoom)
+            return;
+        // Adjust camera so the point under the mouse stays fixed
+        const dx = (screenX - this.canvasW / 2) / oldZoom;
+        const dy = (screenY - this.canvasH / 2) / oldZoom;
+        const worldX = this.x + dx;
+        const worldY = this.y + dy;
+        this.zoom = newZoom;
+        const newDx = (screenX - this.canvasW / 2) / newZoom;
+        const newDy = (screenY - this.canvasH / 2) / newZoom;
+        this.x = worldX - newDx;
+        this.y = worldY - newDy;
+    }
+    /** Convert screen pixel coords to world coords (same as screenToWorld). */
+    screenToGrid(screenX, screenY) {
+        return {
+            x: (screenX - this.canvasW / 2) / this.zoom + this.x,
+            y: (screenY - this.canvasH / 2) / this.zoom + this.y,
+        };
+    }
+    /** Convert world coords to screen pixel coords. */
+    worldToScreen(worldX, worldY) {
+        return {
+            x: (worldX - this.x) * this.zoom + this.canvasW / 2,
+            y: (worldY - this.y) * this.zoom + this.canvasH / 2,
+        };
+    }
+}
+/**
+ * Build a 4×4 column-major transform matrix for GPU shaders.
+ * Maps world coords to NDC (-1..1) with the camera centered.
+ */
+export function cameraMatrix(cam) {
+    const sx = 2 / (cam.width * cam.zoom);
+    const sy = -2 / (cam.height * cam.zoom);
+    const tx = -cam.x * sx;
+    const ty = cam.y * sy;
+    return new Float32Array([
+        sx, 0, 0, 0,
+        0, sy, 0, 0,
+        0, 0, 1, 0,
+        tx, ty, 0, 1,
+    ]);
+}

package/dist/core/src/render/camera-controller.js

@@ -0,0 +1,370 @@
+// ============================================================================
+// CameraController — batteries-included camera controller for renderer plugins
+//
+// Built on the existing core `Camera` math (spherical orbit/pan/zoom). Adds:
+//  - Multi-camera support (named cameras + active selection)
+//  - Lerp/smoothing between current and commanded position/target/rotation
+//  - Orbit/pan/zoom input binding via `RendererInputBus` (no own DOM listeners)
+//  - Real bounding-sphere `frameBounds` (replaces the model-viewer's magic
+//    `distance = 3.5`)
+//
+// Implements `CameraControllerLike` so it can be registered as the active
+// camera provider on a `RendererModuleContext`.
+// ============================================================================
+import { Camera } from "../scene/camera.js";
+const DEFAULT_ORBIT = {
+    rotateSpeed: 0.005,
+    panSpeed: 0.002,
+    zoomSpeed: 0.1,
+    minDistance: 0.1,
+    maxDistance: 500,
+    panButtonMask: 2,
+    shiftPans: true,
+};
+function quatIdentity() {
+    return [0, 0, 0, 1];
+}
+function quatSlerp(a, b, t) {
+    let cosOmega = a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3];
+    let b0 = b[0], b1 = b[1], b2 = b[2], b3 = b[3];
+    if (cosOmega < 0) {
+        b0 = -b0;
+        b1 = -b1;
+        b2 = -b2;
+        b3 = -b3;
+        cosOmega = -cosOmega;
+    }
+    if (cosOmega > 0.9999) {
+        return [
+            a[0] + (b0 - a[0]) * t,
+            a[1] + (b1 - a[1]) * t,
+            a[2] + (b2 - a[2]) * t,
+            a[3] + (b3 - a[3]) * t,
+        ];
+    }
+    const omega = Math.acos(cosOmega);
+    const sinOmega = Math.sin(omega);
+    const s0 = Math.sin((1 - t) * omega) / sinOmega;
+    const s1 = Math.sin(t * omega) / sinOmega;
+    return [
+        a[0] * s0 + b0 * s1,
+        a[1] * s0 + b1 * s1,
+        a[2] * s0 + b2 * s1,
+        a[3] * s0 + b3 * s1,
+    ];
+}
+export class CameraController {
+    cameras = new Map();
+    activeId = null;
+    /** Lerp factor in [0,1]. 0 = instant, 1 = never moves. */
+    lerpFactor;
+    // Per-active-camera rendered (smoothed) state. Keyed by camera id.
+    renderedPos = new Map();
+    renderedTarget = new Map();
+    renderedRot = new Map();
+    /** Optional explicit rotation goal (quaternion). When set, overrides lookAt orientation. */
+    rotationGoal = new Map();
+    initialized = new Map();
+    // Cached CameraState per camera (reused across frames to avoid allocation).
+    cachedState = new Map();
+    // Unsubscribe fns for input bindings (so unbindOrbit can tear them down).
+    orbitUnsubs = [];
+    constructor(opts = {}) {
+        this.lerpFactor = opts.lerpFactor ?? 0;
+        if (opts.defaultCameraId) {
+            this.addCamera(opts.defaultCameraId, new Camera());
+            this.activeId = opts.defaultCameraId;
+        }
+    }
+    // ── Multi-camera management ──
+    addCamera(id, camera) {
+        this.cameras.set(id, camera);
+        if (this.activeId === null)
+            this.activeId = id;
+    }
+    removeCamera(id) {
+        this.cameras.delete(id);
+        this.renderedPos.delete(id);
+        this.renderedTarget.delete(id);
+        this.renderedRot.delete(id);
+        this.rotationGoal.delete(id);
+        this.initialized.delete(id);
+        this.cachedState.delete(id);
+        if (this.activeId === id) {
+            this.activeId = this.cameras.size > 0 ? this.cameras.keys().next().value ?? null : null;
+        }
+    }
+    setActive(id) {
+        if (!this.cameras.has(id))
+            throw new Error(`Camera "${id}" not registered`);
+        this.activeId = id;
+    }
+    getActiveId() {
+        return this.activeId;
+    }
+    getCamera(id) {
+        return this.cameras.get(id);
+    }
+    getActiveCamera() {
+        return this.activeId ? this.cameras.get(this.activeId) ?? null : null;
+    }
+    listCameras() {
+        return Array.from(this.cameras.keys());
+    }
+    // ── Rotation goal (optional quaternion orientation) ──
+    /**
+     * Set an explicit rotation goal (quaternion [x,y,z,w]) for a camera. When
+     * set, the controller slerps toward this orientation instead of deriving
+     * orientation from lookAt(position, target, up). Pass null to revert to
+     * lookAt-derived orientation.
+     */
+    setRotationGoal(id, q) {
+        this.rotationGoal.set(id, q);
+    }
+    // ── CameraControllerLike ──
+    setAspect(w, h) {
+        for (const cam of this.cameras.values()) {
+            cam.setAspect(w, h);
+        }
+    }
+    frameBounds(min, max) {
+        const cam = this.getActiveCamera();
+        if (!cam)
+            return;
+        const cx = (min[0] + max[0]) / 2;
+        const cy = (min[1] + max[1]) / 2;
+        const cz = (min[2] + max[2]) / 2;
+        cam.setTarget(cx, cy, cz);
+        // Bounding-sphere framing: distance = (halfDiag / sin(fov/2)) * padding.
+        // Account for aspect by using the smaller effective FOV.
+        const dx = max[0] - min[0];
+        const dy = max[1] - min[1];
+        const dz = max[2] - min[2];
+        const halfDiag = Math.sqrt(dx * dx + dy * dy + dz * dz) / 2 || 0.1;
+        const fovRad = (cam.fov * Math.PI) / 180;
+        const horizFov = 2 * Math.atan(Math.tan(fovRad / 2) * cam.aspect);
+        const effectiveFov = Math.min(fovRad, horizFov);
+        const padding = 1.5;
+        const distance = (halfDiag / Math.sin(effectiveFov / 2)) * padding;
+        // Scale the depth range to the framed subject: a fixed near/far either
+        // clips large models (framing distance beyond far) or wastes precision
+        // on small ones. Keep 500m far as the floor so ordinary scenes are
+        // unchanged.
+        cam.near = Math.max(0.01, distance / 1000);
+        cam.far = Math.max(500, distance * 8);
+        // Drive the orbit params directly so subsequent orbit/zoom/pan work.
+        cam.distance = Math.max(0.1, distance);
+        cam.yaw = Math.PI * 0.25;
+        cam.pitch = Math.PI * 0.15;
+        // Recompute position from the new spherical params.
+        cam.setPosition(cx + cam.distance * Math.cos(cam.pitch) * Math.sin(cam.yaw), cy + cam.distance * Math.sin(cam.pitch), cz + cam.distance * Math.cos(cam.pitch) * Math.cos(cam.yaw));
+        // Reset smoothing so the framed view snaps instead of lerping from afar.
+        const id = this.activeId;
+        this.initialized.set(id, false);
+    }
+    /**
+     * Returns the smoothed `CameraState` for the active camera (or the given
+     * viewport's camera if multi-viewport mapping is configured). Viewport
+     * index is currently ignored (single active camera); subclasses can
+     * override to map viewports to cameras.
+     */
+    getCameraState(viewportIdx) {
+        void viewportIdx; // single-camera-per-controller for now
+        const id = this.activeId;
+        if (!id) {
+            // Fallback: a default camera at origin looking down -Z.
+            return {
+                position: [0, 5, 10],
+                target: [0, 0, 0],
+                up: [0, 1, 0],
+                fov: 60,
+                near: 0.1,
+                far: 1000,
+                aspect: 1,
+            };
+        }
+        const cam = this.cameras.get(id);
+        this.tickSmoothing(id, cam);
+        // Build (or reuse) a CameraState with cached view/proj matrices so
+        // consumers that call calculateViewProjInto can take the fast path.
+        let state = this.cachedState.get(id);
+        if (!state) {
+            state = {
+                position: [0, 0, 0],
+                target: [0, 0, 0],
+                up: [0, 1, 0],
+                fov: cam.fov,
+                near: cam.near,
+                far: cam.far,
+                aspect: cam.aspect,
+                projectionMatrix: cam.getProjectionMatrix(),
+                viewMatrix: cam.getViewMatrix(),
+            };
+            this.cachedState.set(id, state);
+        }
+        const rp = this.renderedPos.get(id);
+        const rt = this.renderedTarget.get(id);
+        state.position[0] = rp[0];
+        state.position[1] = rp[1];
+        state.position[2] = rp[2];
+        state.target[0] = rt[0];
+        state.target[1] = rt[1];
+        state.target[2] = rt[2];
+        state.fov = cam.fov;
+        state.near = cam.near;
+        state.far = cam.far;
+        state.aspect = cam.aspect;
+        // If a rotation goal is set, the view matrix is derived from it rather
+        // than lookAt; otherwise let the consumer derive view from position/target/up.
+        const rotGoal = this.rotationGoal.get(id);
+        if (rotGoal) {
+            // We don't bake the quaternion into viewMatrix here — consumers that
+            // respect `viewMatrix` will get the lookAt-derived one. A future
+            // extension can build a view matrix from the quaternion; for now the
+            // slerped quaternion is exposed via getRenderedRotation() for callers
+            // that need it (e.g. XR rigs).
+            state.viewMatrix = cam.getViewMatrix();
+        }
+        else {
+            state.viewMatrix = cam.getViewMatrix();
+        }
+        state.projectionMatrix = cam.getProjectionMatrix();
+        return state;
+    }
+    /** Current slerped rotation quaternion for a camera (or identity). */
+    getRenderedRotation(id) {
+        return this.renderedRot.get(id) ?? quatIdentity();
+    }
+    // ── Orbit input binding ──
+    /**
+     * Wires orbit/pan/zoom input from the bus to the active camera. Returns an
+     * unsubscribe function. While bound, left-drag rotates, shift/right-drag
+     * pans, and wheel zooms — matching the model-viewer's OrbitCamera.
+     */
+    bindOrbit(bus, opts = {}) {
+        const o = { ...DEFAULT_ORBIT, ...opts };
+        const unsubs = this.orbitUnsubs;
+        const onDrag = (d) => {
+            const cam = this.getActiveCamera();
+            if (!cam)
+                return;
+            const isPan = (o.shiftPans && d.shift) || (d.buttons & o.panButtonMask) !== 0;
+            if (isPan) {
+                const panX = -d.dx * o.panSpeed * cam.distance;
+                const panY = d.dy * o.panSpeed * cam.distance;
+                cam.pan(panX, panY);
+            }
+            else {
+                cam.orbit(-d.dx * o.rotateSpeed, d.dy * o.rotateSpeed);
+            }
+        };
+        const onWheel = (e) => {
+            const cam = this.getActiveCamera();
+            if (!cam)
+                return;
+            e.preventDefault();
+            const factor = 1 + e.deltaY * o.zoomSpeed * 0.01;
+            cam.distance *= factor;
+            cam.distance = Math.max(o.minDistance, Math.min(o.maxDistance, cam.distance));
+            // Recompute position from the new distance.
+            cam.setPosition(cam.target[0] + cam.distance * Math.cos(cam.pitch) * Math.sin(cam.yaw), cam.target[1] + cam.distance * Math.sin(cam.pitch), cam.target[2] + cam.distance * Math.cos(cam.pitch) * Math.cos(cam.yaw));
+        };
+        unsubs.push(bus.onDrag(onDrag, 100));
+        unsubs.push(bus.onWheel(onWheel, 100));
+        return () => {
+            while (unsubs.length)
+                unsubs.pop()();
+        };
+    }
+    /** Tear down any orbit input bindings. */
+    unbindOrbit() {
+        while (this.orbitUnsubs.length)
+            this.orbitUnsubs.pop()();
+    }
+    // ── Smoothing ──
+    /**
+     * Advance the rendered (smoothed) position/target/rotation toward the
+     * camera's commanded goal by one frame's worth of lerp. Called from
+     * getCameraState so consumers always read post-smoothing state.
+     *
+     * Uses the same `1 - Math.pow(1-lerpFactor, dt*60)` shape as
+     * `CameraSystem`'s third-person smoothing (render/camera.ts:233). We
+     * assume a 60Hz reference frame when dt is unknown (getCameraState has no
+     * dt param); callers that want frame-rate-independent smoothing should
+     * call `tick(dt)` explicitly each frame.
+     */
+    tickSmoothing(id, cam) {
+        const goalPos = cam.position;
+        const goalTarget = cam.target;
+        const goalRot = this.rotationGoal.get(id) ?? null;
+        if (!this.initialized.get(id)) {
+            this.renderedPos.set(id, [goalPos[0], goalPos[1], goalPos[2]]);
+            this.renderedTarget.set(id, [goalTarget[0], goalTarget[1], goalTarget[2]]);
+            this.renderedRot.set(id, goalRot ? [...goalRot] : quatIdentity());
+            this.initialized.set(id, true);
+            return;
+        }
+        const t = 1 - this.lerpFactor; // lerpFactor 0 → t=1 (snap), 1 → t=0 (frozen)
+        const rp = this.renderedPos.get(id);
+        const rt = this.renderedTarget.get(id);
+        rp[0] += (goalPos[0] - rp[0]) * t;
+        rp[1] += (goalPos[1] - rp[1]) * t;
+        rp[2] += (goalPos[2] - rp[2]) * t;
+        rt[0] += (goalTarget[0] - rt[0]) * t;
+        rt[1] += (goalTarget[1] - rt[1]) * t;
+        rt[2] += (goalTarget[2] - rt[2]) * t;
+        if (goalRot) {
+            const rr = this.renderedRot.get(id) ?? quatIdentity();
+            this.renderedRot.set(id, quatSlerp(rr, goalRot, t));
+        }
+    }
+    /**
+     * Frame-rate-independent smoothing tick. Call once per frame with the
+     * frame dt (seconds) before reading getCameraState. If not called, the
+     * controller falls back to the 60Hz assumption inside getCameraState.
+     */
+    tick(dt) {
+        if (this.lerpFactor <= 0) {
+            // Snapping — just ensure initialized.
+            for (const [id, cam] of this.cameras.entries())
+                this.tickSmoothing(id, cam);
+            return;
+        }
+        const t = 1 - Math.pow(this.lerpFactor, dt * 60);
+        for (const [id, cam] of this.cameras.entries()) {
+            const goalPos = cam.position;
+            const goalTarget = cam.target;
+            const goalRot = this.rotationGoal.get(id) ?? null;
+            if (!this.initialized.get(id)) {
+                this.renderedPos.set(id, [goalPos[0], goalPos[1], goalPos[2]]);
+                this.renderedTarget.set(id, [goalTarget[0], goalTarget[1], goalTarget[2]]);
+                this.renderedRot.set(id, goalRot ? [...goalRot] : quatIdentity());
+                this.initialized.set(id, true);
+                continue;
+            }
+            const rp = this.renderedPos.get(id);
+            const rt = this.renderedTarget.get(id);
+            rp[0] += (goalPos[0] - rp[0]) * t;
+            rp[1] += (goalPos[1] - rp[1]) * t;
+            rp[2] += (goalPos[2] - rp[2]) * t;
+            rt[0] += (goalTarget[0] - rt[0]) * t;
+            rt[1] += (goalTarget[1] - rt[1]) * t;
+            rt[2] += (goalTarget[2] - rt[2]) * t;
+            if (goalRot) {
+                const rr = this.renderedRot.get(id) ?? quatIdentity();
+                this.renderedRot.set(id, quatSlerp(rr, goalRot, t));
+            }
+        }
+    }
+    // ── Lifecycle ──
+    dispose() {
+        this.unbindOrbit();
+        this.cameras.clear();
+        this.renderedPos.clear();
+        this.renderedTarget.clear();
+        this.renderedRot.clear();
+        this.rotationGoal.clear();
+        this.initialized.clear();
+        this.cachedState.clear();
+    }
+}