@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/fx/water.js

@@ -0,0 +1,371 @@
+import { plane } from '../geom/index.js';
+import { VERTEX_LAYOUT_3D } from '../render/mesh.js';
+import { auxSuffix, ScenePipelineCache, sceneVariant } from '../render/scene-pipelines.js';
+import { createShaderModule } from '../render/wgsl.js';
+import { WATER_DEPTH_COPY_WGSL, WATER_MAX_WAVES, WATER_WGSL } from './water-wgsl.js';
+/** Floats in the water's params block: 5 vec4 + `WATER_MAX_WAVES` vec4 (144 bytes). */
+export const WATER_PARAMS_FLOATS = 20 + WATER_MAX_WAVES * 4;
+const DEPTH_COPY_FORMAT = 'depth32float';
+const DEFAULT_SHALLOW = [0.1, 0.45, 0.45];
+const DEFAULT_DEEP = [0.01, 0.07, 0.14];
+const DEFAULT_FOAM_COLOR = [0.9, 0.95, 0.97];
+const DEFAULT_WAVES = () => [
+    { scale: 0.35, speed: 0.6, amplitude: 0.25, direction: [1, 0.3] },
+    { scale: 0.9, speed: 0.9, amplitude: 0.12, direction: [-0.4, 1] },
+];
+const PREMULTIPLIED = {
+    color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+    alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+};
+/**
+ * An animated water surface: a plane from `geom`'s `plane` whose shader sums scrolling
+ * analytic wave layers for the normal (and the height when `displace` > 0), lerps a depth-tinted
+ * refraction colour towards a sky reflection by Fresnel, adds the sun's GGX highlight (also to
+ * the emissive target), fades to transparent at the shoreline and foams where the water is
+ * shallower than `foam.width`. `frame.drawable(water, order)` draws it after opaque geometry
+ * (drawables sort as blended); `update(dt)` advances the waves.
+ *
+ * Every field is live; `prepare` packs them into one `WATER_PARAMS_FLOATS` params block per
+ * frame. The sun, its colour and the fog colour (the horizon of the reflection) come from
+ * `frame.lights`; `Sky` present or not.
+ *
+ * Depth: under a depth camera the water tests and writes depth (`less-equal`), so particles and
+ * trails sort against it, and `prepare` copies the scene depth (`depthTarget ?? renderer.target`,
+ * its `SceneTarget.depth`) into its own `depth32float` texture for the depth fade, the shoreline
+ * alpha and the foam. The copy runs before this frame's scene pass, so it holds what the target
+ * held then: the previous frame's depth (which includes this water's own surface, read as "no
+ * information": deep, no foam) or that of an earlier `renderer.render` call this frame. For a
+ * shoreline, draw the water on its own layer in a second view of the same camera, after the
+ * opaque view (`harness/water.ts` does). Without a depth camera there is no copy: the surface is
+ * deep everywhere, foam off, and the pipeline has no depth state.
+ */
+export class Water {
+    /** Surface height (y) above `origin`. Live. */
+    level;
+    /** World position of the plane's centre (`WaterOptions.origin`). Fixed. */
+    origin = new Float32Array(3);
+    /** Linear RGB where the water is shallow. Live. */
+    shallowColor = new Float32Array(3);
+    /** Linear RGB at full depth. Live. */
+    deepColor = new Float32Array(3);
+    /** World units of water depth to full `deepColor`. Live. */
+    depthFade;
+    /** Reflection strength, 0..1. Live. */
+    fresnel;
+    /** Roughness of the sun highlight. Live. */
+    roughness;
+    /** Wave layers; the first `WATER_MAX_WAVES` are uploaded. Live (replace or mutate). */
+    waves;
+    /** Foam settings, or null for none. Live (replace or mutate). */
+    foam;
+    /** Vertex height amplitude. Live. */
+    displace;
+    /** Alpha away from the shoreline. Live. */
+    opacity;
+    /** Where the scene depth is copied from; null for `renderer.target`. Live. */
+    depthTarget;
+    /** See `WaterOptions.readsDepth`. Live. */
+    readsDepth;
+    /** Seconds `update` has advanced; the waves' clock. */
+    time = 0;
+    /** The plane, owned; drawn through this drawable's own pipeline. */
+    mesh;
+    renderer;
+    device;
+    params;
+    paramsBuffer;
+    layout;
+    dummy;
+    dummyGroup;
+    desc;
+    /**
+     * Pipelines per depth format (null: none; a depth one writes depth) × the view target's aux
+     * key, built on first use from `renderer.sceneTargets` (ws/render-10).
+     */
+    pipelines = new ScenePipelineCache();
+    copyLayout;
+    copyPipeline;
+    copyAtt;
+    copyPass;
+    copy = null;
+    copyGroup = null;
+    src = null;
+    srcGroup = null;
+    /** The depth copy ran this frame (`draw` binds it and the shader reads it). */
+    depthOn = false;
+    /** The renderer's `depthCopy` view the hook group was made for (`readsDepth`). */
+    hookView = null;
+    hookGroup = null;
+    /** The group `draw` binds: own copy, the renderer's copy, or the 1×1 stand-in. */
+    depthGroup = null;
+    constructor(renderer, opts = {}) {
+        const device = renderer.device;
+        this.renderer = renderer;
+        this.device = device;
+        this.level = opts.level ?? 0;
+        set3(this.shallowColor, opts.shallowColor ?? DEFAULT_SHALLOW);
+        set3(this.deepColor, opts.deepColor ?? DEFAULT_DEEP);
+        this.depthFade = opts.depthFade ?? 4;
+        this.fresnel = opts.fresnel ?? 0.6;
+        this.roughness = opts.roughness ?? 0.08;
+        this.waves = opts.waves ?? DEFAULT_WAVES();
+        const foam = opts.foam;
+        this.foam =
+            foam === null
+                ? null
+                : { width: foam?.width ?? 0.4, color: foam?.color ?? DEFAULT_FOAM_COLOR };
+        this.displace = opts.displace ?? 0;
+        this.opacity = opts.opacity ?? 0.85;
+        this.depthTarget = opts.depthTarget ?? null;
+        this.readsDepth = opts.readsDepth ?? false;
+        if (opts.origin)
+            set3(this.origin, opts.origin);
+        const geometry = plane({ size: opts.size ?? 100, segments: opts.segments ?? 1 });
+        const ox = this.origin[0];
+        const oz = this.origin[2];
+        if (ox !== 0 || oz !== 0) {
+            const v = geometry.vertices;
+            const stride = geometry.layout.floats;
+            for (let i = 0; i < v.length; i += stride) {
+                v[i] = v[i] + ox;
+                v[i + 2] = v[i + 2] + oz;
+            }
+            geometry.bounds.center[0] += ox;
+            geometry.bounds.center[2] += oz;
+        }
+        this.mesh = renderer.createMesh({ ...geometry, label: 'water' });
+        this.params = new Float32Array(WATER_PARAMS_FLOATS);
+        this.paramsBuffer = device.createBuffer({
+            label: 'water-params',
+            size: this.params.byteLength,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        this.layout = device.createBindGroupLayout({
+            label: 'water-layout',
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: {} },
+                { binding: 1, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'depth' } },
+            ],
+        });
+        this.dummy = device.createTexture({
+            label: 'water-depth-none',
+            size: [1, 1],
+            format: DEPTH_COPY_FORMAT,
+            usage: GPUTextureUsage.TEXTURE_BINDING,
+        });
+        this.dummyGroup = this.makeGroup('water', this.dummy.createView());
+        const module = createShaderModule(device, WATER_WGSL, 'water');
+        this.desc = {
+            label: 'water',
+            layout: device.createPipelineLayout({
+                bindGroupLayouts: [renderer.globalsLayout, this.layout],
+            }),
+            vertex: { module, entryPoint: 'vs', buffers: [VERTEX_LAYOUT_3D.buffer] },
+            fragment: {
+                module,
+                entryPoint: 'fs',
+                targets: renderer.sceneTargets(PREMULTIPLIED),
+            },
+            primitive: { topology: 'triangle-list', cullMode: 'none' },
+        };
+        this.pipelines.set(null, renderer.target.auxKey, device.createRenderPipeline(this.desc));
+        this.copyLayout = device.createBindGroupLayout({
+            label: 'water-depth-copy-layout',
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: 'depth' } },
+            ],
+        });
+        const copyModule = createShaderModule(device, WATER_DEPTH_COPY_WGSL, 'water-depth-copy');
+        this.copyPipeline = device.createRenderPipeline({
+            label: 'water-depth-copy',
+            layout: device.createPipelineLayout({ bindGroupLayouts: [this.copyLayout] }),
+            vertex: { module: copyModule, entryPoint: 'vs' },
+            fragment: { module: copyModule, entryPoint: 'fs', targets: [] },
+            primitive: { topology: 'triangle-list' },
+            depthStencil: { format: DEPTH_COPY_FORMAT, depthWriteEnabled: true, depthCompare: 'always' },
+        });
+        this.copyAtt = {
+            view: undefined,
+            depthClearValue: 1,
+            depthLoadOp: 'clear',
+            depthStoreOp: 'store',
+        };
+        this.copyPass = {
+            label: 'water-depth-copy',
+            colorAttachments: [],
+            depthStencilAttachment: this.copyAtt,
+        };
+    }
+    /** Advance the waves' clock. */
+    update(dt) {
+        this.time += dt;
+    }
+    /**
+     * Copy the scene depth (under a depth camera) and pack the live fields into the params block
+     * (`WATER_PARAMS_FLOATS` floats: shallow rgb + opacity, deep rgb + depthFade, fresnel,
+     * roughness, displace, level, foam rgb + width, time, wave count, depth copy on, 0, then
+     * scale, speed, amplitude, direction angle per wave). Called by the renderer once per frame.
+     * No allocation in steady state.
+     */
+    prepare(encoder, frame) {
+        // With `readsDepth` the renderer's hook (`afterOpaque`) supplies this frame's depth.
+        this.depthOn = this.readsDepth ? false : this.copyDepth(encoder, frame);
+        this.depthGroup = this.depthOn ? this.copyGroup : null;
+        const p = this.params;
+        p[0] = this.shallowColor[0];
+        p[1] = this.shallowColor[1];
+        p[2] = this.shallowColor[2];
+        p[3] = this.opacity;
+        p[4] = this.deepColor[0];
+        p[5] = this.deepColor[1];
+        p[6] = this.deepColor[2];
+        p[7] = this.depthFade;
+        p[8] = this.fresnel;
+        p[9] = this.roughness;
+        p[10] = this.displace;
+        p[11] = this.level;
+        const foam = this.foam;
+        p[12] = foam ? (foam.color[0] ?? 0) : 0;
+        p[13] = foam ? (foam.color[1] ?? 0) : 0;
+        p[14] = foam ? (foam.color[2] ?? 0) : 0;
+        p[15] = foam ? foam.width : 0;
+        const count = Math.min(this.waves.length, WATER_MAX_WAVES);
+        p[16] = this.time;
+        p[17] = count;
+        p[18] = this.depthOn ? 1 : 0;
+        p[19] = this.origin[1];
+        for (let i = 0; i < WATER_MAX_WAVES; i++) {
+            const o = 20 + i * 4;
+            const w = i < count ? this.waves[i] : null;
+            p[o] = w ? w.scale : 0;
+            p[o + 1] = w ? w.speed : 0;
+            p[o + 2] = w ? w.amplitude : 0;
+            p[o + 3] = w ? Math.atan2(w.direction[1], w.direction[0]) : 0;
+        }
+        this.device.queue.writeBuffer(this.paramsBuffer, 0, p);
+    }
+    /** Draw inside the scene pass: the plane, a depth-writing pipeline when the frame has depth. */
+    draw(pass, frame) {
+        const mesh = this.mesh;
+        if (mesh.indexCount <= 0)
+            return;
+        const fmt = frame?.depthFormat ?? null;
+        pass.setPipeline(this.pipelineFor(fmt, frame ? frame.auxKey : this.renderer.target.auxKey));
+        pass.setBindGroup(1, this.depthGroup ?? this.dummyGroup);
+        pass.setVertexBuffer(0, mesh.vertexBuffer);
+        pass.setIndexBuffer(mesh.indexBuffer, mesh.indexFormat);
+        pass.drawIndexed(mesh.indexCount);
+    }
+    /**
+     * The renderer's depth hook (`readsDepth`): bind this frame's opaque depth copy and flip the
+     * shader's depth flag on (a 4-byte write; `queue.writeBuffer` lands before the frame's
+     * commands run). A new bind group only when the copy texture changed (resize).
+     */
+    afterOpaque(_encoder, view) {
+        if (view.depthView !== this.hookView) {
+            this.hookView = view.depthView;
+            this.hookGroup = this.makeGroup('water-hook', view.depthView);
+        }
+        this.depthOn = true;
+        this.depthGroup = this.hookGroup;
+        const p = this.params;
+        p[18] = 1;
+        this.device.queue.writeBuffer(this.paramsBuffer, 18 * 4, p.buffer, 18 * 4, 4);
+    }
+    copyDepth(encoder, frame) {
+        if (!frame?.depthFormat)
+            return false;
+        const src = (this.depthTarget ?? this.renderer.target).depth;
+        if (!src)
+            return false;
+        const device = this.device;
+        if (!this.copy || this.copy.width !== src.width || this.copy.height !== src.height) {
+            this.copy?.destroy();
+            this.copy = device.createTexture({
+                label: 'water-depth',
+                size: [src.width, src.height],
+                format: DEPTH_COPY_FORMAT,
+                usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
+            });
+            const view = this.copy.createView();
+            this.copyAtt.view = view;
+            this.copyGroup = this.makeGroup('water-soft', view);
+        }
+        if (this.src !== src) {
+            this.src = src;
+            this.srcGroup = device.createBindGroup({
+                label: 'water-depth-copy',
+                layout: this.copyLayout,
+                entries: [{ binding: 0, resource: src.view }],
+            });
+        }
+        const pass = encoder.beginRenderPass(this.copyPass);
+        pass.setPipeline(this.copyPipeline);
+        pass.setBindGroup(0, this.srcGroup);
+        pass.draw(3);
+        pass.end();
+        return true;
+    }
+    makeGroup(label, depth) {
+        return this.device.createBindGroup({
+            label,
+            layout: this.layout,
+            entries: [
+                { binding: 0, resource: { buffer: this.paramsBuffer } },
+                { binding: 1, resource: depth },
+            ],
+        });
+    }
+    pipelineFor(format, aux) {
+        const p = this.pipelines.get(format, aux);
+        if (p)
+            return p;
+        return this.pipelines.set(format, aux, this.device.createRenderPipeline(sceneVariant(this.desc, this.renderer.sceneTargets(PREMULTIPLIED, aux), `water${format ? `:${format}` : ''}${auxSuffix(aux)}`, format ? { format, depthWriteEnabled: true, depthCompare: 'less-equal' } : undefined)));
+    }
+    destroy() {
+        this.paramsBuffer.destroy();
+        this.dummy.destroy();
+        this.copy?.destroy();
+        this.copy = null;
+        this.mesh.destroy();
+    }
+}
+/**
+ * One wave layer's value and gradient at field point (`px`, `py`): the shader's `water_wave`.
+ * Writes `[value, d/dx, d/dy]` into `out`.
+ */
+function wave(px, py, out) {
+    const a = px + 0.6 * Math.sin(1.3 * py);
+    const b = 0.8 * py + 0.5 * Math.sin(0.9 * px);
+    const sa = Math.sin(a);
+    const ca = Math.cos(a);
+    const sb = Math.sin(b);
+    const cb = Math.cos(b);
+    out[0] = sa * cb;
+    out[1] = ca * cb - sa * sb * 0.45 * Math.cos(0.9 * px);
+    out[2] = ca * cb * 0.78 * Math.cos(1.3 * py) - sa * sb * 0.8;
+}
+const waveOut = [0, 0, 0];
+/**
+ * The surface height at world (`x`, `z`) at time `t` (default `water.time`): the origin's y
+ * plus `level` plus `displace` times the summed wave layers, the formula the vertex shader
+ * runs. Pure; no allocation. With `displace` 0 it is `origin[1] + level`.
+ */
+export function waterHeight(water, x, z, t = water.time) {
+    let h = 0;
+    const n = Math.min(water.waves.length, WATER_MAX_WAVES);
+    for (let i = 0; i < n; i++) {
+        const w = water.waves[i];
+        const angle = Math.atan2(w.direction[1], w.direction[0]);
+        const dx = Math.cos(angle);
+        const dz = Math.sin(angle);
+        wave(x * w.scale + dx * t * w.speed, z * w.scale + dz * t * w.speed, waveOut);
+        h += w.amplitude * waveOut[0];
+    }
+    return water.origin[1] + water.level + water.displace * h;
+}
+function set3(out, v) {
+    out[0] = v[0] ?? 0;
+    out[1] = v[1] ?? 0;
+    out[2] = v[2] ?? 0;
+}

package/dist/geom/collide/bvh.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The static collider: every source's triangles flattened into one world-space `Float32Array`
+ * (nine floats per triangle) under a bounding-volume hierarchy, built once by median split along
+ * the widest centroid axis. Each source owns a contiguous block of triangles and of nodes, so a
+ * moving platform refits its own sub-tree and the small top-level tree over the sources, never
+ * the rest. Queries (`queries.ts`) walk the flat node arrays with a shared stack; nothing here
+ * allocates after the build.
+ *
+ * Node layout, index `i`: `nodeMin`/`nodeMax` at `3i`; `nodeLeaf[i]` 1 for a leaf; for a leaf
+ * `nodeA[i]` is the first triangle and `nodeB[i]` the count, for an inner node they are the two
+ * children. A removed or empty source keeps an empty root box (min +∞, max −∞) that no query
+ * enters.
+ */
+import type { Geometry } from '../geometry.js';
+import type { Heightfield } from '../heightfield.js';
+import { type GridSource } from './grid.js';
+/** A 3×4 row-major matrix (`Transform.world`, 12 floats) or a 4×4 column-major one (16 floats). */
+export type ColliderTransform = ArrayLike<number>;
+/** What every triangle-set source shares: its placement, layer and user data. */
+interface TriangleSourceBase {
+    transform?: ColliderTransform;
+    /** Collision layer, a bit index 0..31 (`layerMask` tests `1 << layer`). Default 0. */
+    layer?: number;
+    /** Handed back on every hit of this source; not serialised. */
+    userData?: unknown;
+}
+/** A `Geometry` (any layout whose first three floats per vertex are the position), placed. */
+export interface GeometryMeshSource extends TriangleSourceBase {
+    geometry: Geometry;
+}
+/**
+ * Bare triangles (ws/geom-3): `positions` is x, y, z per vertex (3 floats, no other lanes) and
+ * `indices` three per triangle, as a bake input or a hand-built proxy holds them. Builds and
+ * refits exactly as a `{ geometry }` source does.
+ */
+export interface PositionsSource extends TriangleSourceBase {
+    positions: Float32Array;
+    indices: Uint16Array | Uint32Array;
+}
+/** A triangle set: a `Geometry` or positions-only triangles, optionally placed. */
+export type GeometrySource = GeometryMeshSource | PositionsSource;
+/** A heightfield, one quad (two triangles) per cell, in its own world placement. */
+export interface HeightfieldSource {
+    heightfield: Heightfield;
+    layer?: number;
+    userData?: unknown;
+}
+/** A 2D tile grid: each solid cell is a box in xz (see `grid.ts`). */
+export interface TileGridSource {
+    grid: GridSource;
+    layer?: number;
+    userData?: unknown;
+}
+export type ColliderSource = GeometrySource | HeightfieldSource | TileGridSource;
+export interface StaticColliderOptions {
+    /** Most triangles per BVH leaf. Default 4. */
+    leafSize?: number;
+}
+/** The kinds a source can be, as stored (and serialised): geometry 0, heightfield 1, grid 2. */
+export type SourceKind = 0 | 1 | 2;
+export declare const SOURCE_GEOMETRY = 0;
+export declare const SOURCE_HEIGHTFIELD = 1;
+export declare const SOURCE_GRID = 2;
+/** One source's record inside the collider. */
+export interface SourceRecord {
+    kind: SourceKind;
+    /** First triangle and count in `tris`. */
+    start: number;
+    count: number;
+    /** The source's root node, and its node block `[nodeStart, nodeEnd)`. */
+    root: number;
+    nodeStart: number;
+    nodeEnd: number;
+    layer: number;
+    removed: boolean;
+    /** Geometry sources keep their untransformed triangles (nine floats each) for `refit`. */
+    local: Float32Array | null;
+    userData: unknown;
+}
+export interface ColliderBounds {
+    min: [number, number, number];
+    max: [number, number, number];
+}
+/**
+ * A world of static triangles under a BVH. Build with `createStaticCollider`, query with
+ * `raycast`, `overlap`, `sweep` and `slide`, ship with `exportCollider`.
+ */
+export declare class StaticCollider {
+    /** World-space triangles, nine floats each, in BVH leaf order. */
+    readonly tris: Float32Array;
+    /** The source index of each triangle. */
+    readonly triSource: Uint32Array;
+    readonly nodeMin: Float32Array;
+    readonly nodeMax: Float32Array;
+    readonly nodeLeaf: Uint8Array;
+    readonly nodeA: Int32Array;
+    readonly nodeB: Int32Array;
+    /** The root node index. */
+    readonly root: number;
+    /** Top-level nodes over the sources occupy `[0, topCount)` (0 when there is one source). */
+    readonly topCount: number;
+    readonly sources: SourceRecord[];
+    readonly leafSize: number;
+    /** The union of every live source, kept current by `refit` and `remove`. */
+    readonly bounds: ColliderBounds;
+    constructor(parts: {
+        tris: Float32Array;
+        triSource: Uint32Array;
+        nodeMin: Float32Array;
+        nodeMax: Float32Array;
+        nodeLeaf: Uint8Array;
+        nodeA: Int32Array;
+        nodeB: Int32Array;
+        root: number;
+        topCount: number;
+        sources: SourceRecord[];
+        leafSize: number;
+    });
+    /** Triangles in the live (not removed) sources. */
+    get triangleCount(): number;
+    /** Number of sources, removed ones included (indices stay stable). */
+    get sourceCount(): number;
+    /** The `userData` of a source (-1 or out of range gives `undefined`). */
+    userData(source: number): unknown;
+    /**
+     * Moves a geometry source to `transform` (a 3×4 `Transform.world` or a 4×4 column-major
+     * matrix): rewrites its world triangles from the local copy, refits its leaves and inner nodes
+     * bottom-up, then the top-level nodes. Nothing is rebuilt; a tree whose leaves have drifted far
+     * apart only gets looser. Throws for a heightfield or grid source.
+     */
+    refit(sourceIndex: number, transform: ColliderTransform): void;
+    /** Drops a source from every query (its root box becomes empty). Indices do not shift. */
+    remove(sourceIndex: number): void;
+    /** Recomputes the nodes of one block from its leaves up (children always follow parents). */
+    private refitBlock;
+    private refitTop;
+    private updateBounds;
+}
+/**
+ * Writes `m × (x, y, z, 1)` into `out` at `o`. `m` is a 3×4 row-major matrix (12 floats, as
+ * `Transform.world`) or a 4×4 column-major one (16 floats, as `Camera.view`). Anything else throws.
+ */
+export declare function applyTransform(m: ColliderTransform, x: number, y: number, z: number, out: Float32Array, o: number): void;
+/**
+ * Builds a `StaticCollider` over `sources`. Every source becomes a block of triangles (world
+ * space) and a BVH sub-tree (median split on the widest centroid axis, leaves of at most
+ * `leafSize` triangles, default 4); a top-level tree over the sources' roots joins them.
+ * Build-time allocation only; queries then allocate nothing.
+ */
+export declare function createStaticCollider(sources: ColliderSource[], opts?: StaticColliderOptions): StaticCollider;
+export {};