@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/render/bindings.js

@@ -0,0 +1,281 @@
+import { defaultTextures } from './texture.js';
+/** First binding of `BindingDesc.buffers` (textures stop at 15, so up to 14 texture slots). */
+export const BUFFER_BINDING_BASE = 16;
+export function hasBindings(desc) {
+    return ((desc.uniformBytes ?? 0) > 0 || (desc.textures ?? 0) > 0 || (desc.buffers?.length ?? 0) > 0);
+}
+/** The view dimension of texture slot `slot` under `desc.viewDimension` (default `'2d'`). */
+export function slotViewDimension(desc, slot) {
+    const d = desc.viewDimension;
+    if (d === undefined)
+        return '2d';
+    if (typeof d === 'string')
+        return d;
+    return d[slot] ?? '2d';
+}
+/** 1×1, 1-layer white `'2d-array'` views, one per device: the default for unbound array slots. */
+const whiteArrays = new WeakMap();
+function whiteArrayView(device) {
+    let view = whiteArrays.get(device);
+    if (!view) {
+        const texture = device.createTexture({
+            label: 'white-array',
+            size: [1, 1, 1],
+            format: 'rgba8unorm',
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+        });
+        device.queue.writeTexture({ texture }, new Uint8Array([255, 255, 255, 255]), { bytesPerRow: 4 }, [1, 1, 1]);
+        view = texture.createView({ label: 'white-array', dimension: '2d-array' });
+        whiteArrays.set(device, view);
+    }
+    return view;
+}
+export function createBindingLayout(device, desc, label, dynamicUniform = false) {
+    const vis = desc.visibility ?? GPUShaderStage.FRAGMENT | GPUShaderStage.VERTEX;
+    const entries = [];
+    if ((desc.uniformBytes ?? 0) > 0) {
+        entries.push({
+            binding: 0,
+            visibility: vis,
+            buffer: dynamicUniform ? { hasDynamicOffset: true } : {},
+        });
+    }
+    const n = desc.textures ?? 0;
+    if (n > 0) {
+        entries.push({ binding: 1, visibility: vis, sampler: {} });
+        for (let i = 0; i < n; i++) {
+            const viewDimension = slotViewDimension(desc, i);
+            entries.push({
+                binding: 2 + i,
+                visibility: vis,
+                texture: viewDimension === '2d' ? { sampleType: 'float' } : { sampleType: 'float', viewDimension },
+            });
+        }
+    }
+    const nb = desc.buffers?.length ?? 0;
+    for (let i = 0; i < nb; i++) {
+        entries.push({
+            binding: BUFFER_BINDING_BASE + i,
+            visibility: vis,
+            buffer: { type: 'read-only-storage' },
+        });
+    }
+    return device.createBindGroupLayout({ label, entries });
+}
+/** Bind groups kept for recently used view sets (ping-pong flips between two). */
+const GROUP_CACHE = 4;
+/** Initial per-draw slots (including the shared slot 0). Grows by doubling. */
+const INITIAL_DRAW_SLOTS = 16;
+/**
+ * Owns the uniform buffer + bind group for one binding set; rebuilds the group lazily.
+ * Bind groups for the last few texture sets are cached, so alternating textures (ping-pong)
+ * allocates nothing after the first round. Every texture slot starts bound to a 1×1 white
+ * texture (`defaultView`, or `defaultTextures(device).white` when none is given; a 1-layer white
+ * array for `'2d-array'` slots), so a material with four slots draws with none of them set;
+ * `setTexture` later rebuilds the group.
+ */
+export class BindingSet {
+    device;
+    sampler;
+    label;
+    layout;
+    /** Replaced when a per-draw set grows. */
+    uniformBuffer;
+    /** True when the uniform binding takes a dynamic offset (see `BindingSetOptions.perDraw`). */
+    perDraw;
+    /** Uniform block size in bytes (rounded up to 16), 0 when there is none. */
+    blockBytes;
+    /** Byte distance between per-draw blocks (block size rounded up to the offset alignment). */
+    stride;
+    views;
+    buffers;
+    group = null;
+    cache = [];
+    staging = null;
+    stagingF32 = null;
+    drawSlots = 0;
+    constructor(device, desc, sampler, defaultView, label, opts = {}) {
+        this.device = device;
+        this.sampler = sampler;
+        this.label = label;
+        const bytes = desc.uniformBytes ?? 0;
+        this.blockBytes = Math.ceil(bytes / 16) * 16;
+        this.perDraw = !!opts.perDraw;
+        if (this.perDraw && bytes <= 0) {
+            throw new Error(`${label}: perDraw uniforms need uniformBytes > 0`);
+        }
+        const align = device.limits?.minUniformBufferOffsetAlignment ?? 256;
+        this.stride = this.perDraw ? Math.ceil(this.blockBytes / align) * align : this.blockBytes;
+        this.layout = createBindingLayout(device, desc, `${label}-layout`, this.perDraw);
+        if (this.perDraw) {
+            this.staging = new Uint8Array(this.stride * INITIAL_DRAW_SLOTS);
+            this.stagingF32 = new Float32Array(this.staging.buffer);
+        }
+        this.uniformBuffer = bytes > 0 ? this.makeUniformBuffer() : null;
+        const n = desc.textures ?? 0;
+        // Unset 2D slots read white: the caller's view when it has one, else the device's registry.
+        const white = n > 0 ? (defaultView ?? defaultTextures(device).white.view) : null;
+        this.views = new Array(n).fill(white);
+        for (let i = 0; i < n; i++) {
+            if (slotViewDimension(desc, i) === '2d-array')
+                this.views[i] = whiteArrayView(device);
+        }
+        this.buffers = desc.buffers ? [...desc.buffers] : [];
+    }
+    setUniforms(data, byteOffset = 0) {
+        if (!this.uniformBuffer)
+            throw new Error(`${this.label}: no uniforms declared`);
+        if (ArrayBuffer.isView(data)) {
+            this.device.queue.writeBuffer(this.uniformBuffer, byteOffset, data.buffer, data.byteOffset, data.byteLength);
+            // Keep slot 0 on the CPU too, so a grown buffer can be refilled.
+            if (this.staging)
+                this.stageShared(data.buffer, data.byteOffset, data.byteLength, byteOffset);
+        }
+        else {
+            this.device.queue.writeBuffer(this.uniformBuffer, byteOffset, data);
+            if (this.staging)
+                this.stageShared(data, 0, data.byteLength, byteOffset);
+        }
+    }
+    /** Per-draw blocks recorded since the last flush. */
+    get drawCount() {
+        return this.drawSlots;
+    }
+    /**
+     * Stage one per-draw uniform block (f32s; the rest of the block reads 0) and return its
+     * dynamic offset. Uploaded by `flushDrawUniforms`, normally called by the renderer.
+     */
+    pushDrawUniforms(data) {
+        if (!this.perDraw)
+            throw new Error(`${this.label}: per-draw uniforms not enabled`);
+        if (data.length * 4 > this.blockBytes) {
+            throw new Error(`${this.label}: per-draw uniforms are ${data.length * 4} bytes, block is ${this.blockBytes}`);
+        }
+        const slot = ++this.drawSlots;
+        const offset = slot * this.stride;
+        if (offset + this.stride > this.staging.byteLength) {
+            const next = new Uint8Array(this.staging.byteLength * 2);
+            next.set(this.staging);
+            this.staging = next;
+            this.stagingF32 = new Float32Array(next.buffer);
+        }
+        const f = this.stagingF32;
+        const o = offset / 4;
+        const n = data.length;
+        for (let i = 0; i < n; i++)
+            f[o + i] = data[i];
+        f.fill(0, o + n, o + this.blockBytes / 4);
+        return offset;
+    }
+    /** Upload this frame's per-draw blocks (growing the buffer if needed) and reset the count. */
+    flushDrawUniforms() {
+        const n = this.drawSlots;
+        if (n === 0 || !this.staging)
+            return;
+        this.drawSlots = 0;
+        const needed = (n + 1) * this.stride;
+        if (needed > this.uniformBuffer.size) {
+            this.uniformBuffer.destroy();
+            this.uniformBuffer = this.makeUniformBuffer();
+            this.invalidateGroups();
+            this.device.queue.writeBuffer(this.uniformBuffer, 0, this.staging.buffer, 0, needed);
+            return;
+        }
+        this.device.queue.writeBuffer(this.uniformBuffer, this.stride, this.staging.buffer, this.stride, n * this.stride);
+    }
+    /** Drop this frame's per-draw blocks without uploading. */
+    discardDrawUniforms() {
+        this.drawSlots = 0;
+    }
+    setTexture(slot, tex) {
+        if (slot < 0 || slot >= this.views.length) {
+            throw new Error(`${this.label}: texture slot ${slot} out of range`);
+        }
+        const view = 'view' in tex ? tex.view : tex;
+        if (this.views[slot] === view)
+            return;
+        this.views[slot] = view;
+        this.group = null;
+    }
+    /** Rebind storage buffer slot `i` (`@binding(BUFFER_BINDING_BASE + i)`); groups rebuild lazily. */
+    setBuffer(slot, buffer) {
+        if (slot < 0 || slot >= this.buffers.length) {
+            throw new Error(`${this.label}: buffer slot ${slot} out of range`);
+        }
+        if (this.buffers[slot] === buffer)
+            return;
+        this.buffers[slot] = buffer;
+        this.invalidateGroups();
+    }
+    /** Build a bind group for an explicit set of views (callers cache it). */
+    createGroup(views = this.views) {
+        const entries = [];
+        if (this.uniformBuffer) {
+            entries.push({
+                binding: 0,
+                resource: this.perDraw
+                    ? { buffer: this.uniformBuffer, size: this.blockBytes }
+                    : { buffer: this.uniformBuffer },
+            });
+        }
+        if (views.length) {
+            entries.push({ binding: 1, resource: this.sampler });
+            views.forEach((v, i) => {
+                entries.push({ binding: 2 + i, resource: v });
+            });
+        }
+        this.buffers.forEach((b, i) => {
+            entries.push({ binding: BUFFER_BINDING_BASE + i, resource: { buffer: b } });
+        });
+        return this.device.createBindGroup({
+            label: `${this.label}-group`,
+            layout: this.layout,
+            entries,
+        });
+    }
+    get bindGroup() {
+        if (!this.group)
+            this.group = this.cachedGroup();
+        return this.group;
+    }
+    destroy() {
+        this.uniformBuffer?.destroy();
+    }
+    cachedGroup() {
+        const views = this.views;
+        const cache = this.cache;
+        for (let i = 0; i < cache.length; i++) {
+            const c = cache[i];
+            let same = true;
+            for (let j = 0; j < views.length; j++) {
+                if (c.views[j] !== views[j]) {
+                    same = false;
+                    break;
+                }
+            }
+            if (same)
+                return c.group;
+        }
+        const group = this.createGroup();
+        if (cache.length >= GROUP_CACHE)
+            cache.shift();
+        cache.push({ views: views.slice(), group });
+        return group;
+    }
+    stageShared(src, srcOffset, bytes, at) {
+        const n = Math.max(0, Math.min(bytes, this.stride - at));
+        if (n > 0)
+            this.staging.set(new Uint8Array(src, srcOffset, n), at);
+    }
+    invalidateGroups() {
+        this.group = null;
+        this.cache.length = 0;
+    }
+    makeUniformBuffer() {
+        return this.device.createBuffer({
+            label: `${this.label}-uniforms`,
+            size: this.staging ? this.staging.byteLength : this.blockBytes,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+    }
+}

package/dist/render/blend.d.ts

@@ -0,0 +1,13 @@
+/**
+ * How a material or fullscreen pass blends into its target (`MaterialDesc.blend`,
+ * `FullscreenPassDesc.blend`):
+ *
+ * - `alpha`: straight alpha (`rgb * a + dst * (1 - a)`). Default.
+ * - `premultiplied`: shader outputs rgb already multiplied by alpha.
+ * - `additive`: `rgb * a + dst`. Destination alpha untouched. Glows, sparks.
+ * - `opaque`: overwrite.
+ * - `multiply`: `dst * rgb` (colour factors `dst` / `zero`); destination alpha kept (alpha
+ *   factors `zero` / `one`). Decals, stains, tinted glass: white leaves the surface alone.
+ */
+export type RenderBlendMode = 'alpha' | 'premultiplied' | 'additive' | 'opaque' | 'multiply';
+export declare function blendState(mode: RenderBlendMode): GPUBlendState | undefined;

package/dist/render/blend.js

@@ -0,0 +1,26 @@
+export function blendState(mode) {
+    switch (mode) {
+        case 'opaque':
+            return undefined;
+        case 'alpha':
+            return {
+                color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+            };
+        case 'premultiplied':
+            return {
+                color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+            };
+        case 'additive':
+            return {
+                color: { srcFactor: 'src-alpha', dstFactor: 'one', operation: 'add' },
+                alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
+            };
+        case 'multiply':
+            return {
+                color: { srcFactor: 'dst', dstFactor: 'zero', operation: 'add' },
+                alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
+            };
+    }
+}

package/dist/render/camera-2d.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 2D camera follow (ws/ergo-2d-2): the platformer camera every 2D game rewrote. A dead zone
+ * the target moves inside without the view moving, look-ahead toward the target's velocity,
+ * exponential smoothing, and a world rectangle the view never leaves. It drives an ortho2d
+ * `Camera` through `camera.x` and `camera.y` only (the view's top-left in design px) and reads
+ * `camera.screen` and `camera.zoom` for the view size; nothing else on the camera is touched.
+ *
+ * Per `update(dt, targetX, targetY, velX, velY)`:
+ *  1. the anchor moves just enough to keep the target inside the dead zone (none: it tracks);
+ *  2. the look-ahead eases toward `sign(vel) × lookAhead` with time constant `lookAheadSmoothing`;
+ *  3. the view centre eases toward `anchor + lookAhead` with time constant `smoothing`;
+ *  4. the view rect is clamped inside `bounds` (a view wider than the bounds is centred).
+ * Every easing is `1 - exp(-dt / tau)`, so the result depends on `dt` alone. `teleport` puts
+ * everything at a point with no easing. No allocation per frame.
+ */
+import type { Camera } from './camera.js';
+/** What the follow needs from a `Camera`. */
+export type Follow2DCamera = Pick<Camera, 'x' | 'y' | 'zoom' | 'screen'>;
+export interface Follow2DBounds {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+}
+export interface Follow2DOptions {
+    /** Box around the anchor (world px) the target moves inside freely. Default `0 × 0`. */
+    deadZone?: {
+        w: number;
+        h: number;
+    };
+    /** How far ahead of the target (world px) the view leads along each moving axis. Default 0. */
+    lookAhead?: {
+        x: number;
+        y: number;
+    };
+    /** Time constant (s) of the look-ahead easing. Default 0.25; 0 is instant. */
+    lookAheadSmoothing?: number;
+    /** Time constant (s) of the view's easing toward its goal. Default 0 (instant). */
+    smoothing?: number;
+    /** World rect the view stays inside. Mutate `follow.bounds` later to change it. */
+    bounds?: Follow2DBounds;
+    /** First `update` snaps to the target instead of easing from the camera's position. Default true. */
+    snapOnStart?: boolean;
+}
+export interface Follow2D {
+    /** View centre, world px (what the camera shows at its middle). */
+    readonly x: number;
+    readonly y: number;
+    /** Dead-zone centre, world px. */
+    readonly anchorX: number;
+    readonly anchorY: number;
+    /** Current look-ahead offset, world px. */
+    readonly lookX: number;
+    readonly lookY: number;
+    readonly deadZone: {
+        w: number;
+        h: number;
+    };
+    readonly lookAhead: {
+        x: number;
+        y: number;
+    };
+    lookAheadSmoothing: number;
+    smoothing: number;
+    bounds: Follow2DBounds | null;
+    /** Advance by `dt` seconds toward `(targetX, targetY)` moving at `(velX, velY)`; writes the camera. */
+    update(dt: number, targetX: number, targetY: number, velX?: number, velY?: number): void;
+    /** Put the anchor and the view at `(x, y)` with no easing and no look-ahead; writes the camera. */
+    teleport(x: number, y: number): void;
+}
+/** Make a `Follow2D` over `camera`. Allocates once. */
+export declare function createFollow2D(camera: Follow2DCamera, opts?: Follow2DOptions): Follow2D;

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

@@ -0,0 +1,92 @@
+function ease(dt, tau) {
+    return tau > 0 ? 1 - Math.exp(-dt / tau) : 1;
+}
+/** Make a `Follow2D` over `camera`. Allocates once. */
+export function createFollow2D(camera, opts = {}) {
+    const deadZone = { w: opts.deadZone?.w ?? 0, h: opts.deadZone?.h ?? 0 };
+    const lookAhead = { x: opts.lookAhead?.x ?? 0, y: opts.lookAhead?.y ?? 0 };
+    let started = !(opts.snapOnStart ?? true);
+    let ax = camera.x + camera.screen.width / 2;
+    let ay = camera.y + camera.screen.height / 2;
+    let x = ax;
+    let y = ay;
+    let lx = 0;
+    let ly = 0;
+    function clampAndWrite() {
+        const b = follow.bounds;
+        if (b) {
+            const hw = camera.screen.width / (2 * camera.zoom);
+            const hh = camera.screen.height / (2 * camera.zoom);
+            x =
+                b.maxX - b.minX <= 2 * hw
+                    ? (b.minX + b.maxX) / 2
+                    : Math.min(Math.max(x, b.minX + hw), b.maxX - hw);
+            y =
+                b.maxY - b.minY <= 2 * hh
+                    ? (b.minY + b.maxY) / 2
+                    : Math.min(Math.max(y, b.minY + hh), b.maxY - hh);
+        }
+        camera.x = x - camera.screen.width / 2;
+        camera.y = y - camera.screen.height / 2;
+    }
+    const follow = {
+        get x() {
+            return x;
+        },
+        get y() {
+            return y;
+        },
+        get anchorX() {
+            return ax;
+        },
+        get anchorY() {
+            return ay;
+        },
+        get lookX() {
+            return lx;
+        },
+        get lookY() {
+            return ly;
+        },
+        deadZone,
+        lookAhead,
+        lookAheadSmoothing: opts.lookAheadSmoothing ?? 0.25,
+        smoothing: opts.smoothing ?? 0,
+        bounds: opts.bounds ?? null,
+        update(dt, tx, ty, vx = 0, vy = 0) {
+            if (!started) {
+                started = true;
+                follow.teleport(tx, ty);
+                return;
+            }
+            const hw = deadZone.w / 2;
+            const hh = deadZone.h / 2;
+            if (tx < ax - hw)
+                ax = tx + hw;
+            else if (tx > ax + hw)
+                ax = tx - hw;
+            if (ty < ay - hh)
+                ay = ty + hh;
+            else if (ty > ay + hh)
+                ay = ty - hh;
+            const kl = ease(dt, follow.lookAheadSmoothing);
+            lx += (Math.sign(vx) * lookAhead.x - lx) * kl;
+            ly += (Math.sign(vy) * lookAhead.y - ly) * kl;
+            const k = ease(dt, follow.smoothing);
+            x += (ax + lx - x) * k;
+            y += (ay + ly - y) * k;
+            clampAndWrite();
+        },
+        teleport(px, py) {
+            started = true;
+            ax = px;
+            ay = py;
+            x = px;
+            y = py;
+            lx = 0;
+            ly = 0;
+            clampAndWrite();
+        },
+    };
+    return follow;
+}