@driftengine/core 3.61.0

package/src/render/planarReflectionDraw.ts

@@ -0,0 +1,87 @@
+import type { Camera } from './camera.ts';
+
+/**
+ * What a planar reflection *is*, before any of it touches a device.
+ *
+ * Three decisions, none of which is a binding: where the mirrored camera stands, which half of
+ * the world it may draw, and how large the target may be. A second copy of any of them is a
+ * mirror that disagrees with itself — a reflection shot from a slightly different place, or one
+ * that leaks the near bank of a pool into the water in front of it — and every one of those
+ * reads as a shading problem rather than as a camera one. That is the 2026-08-13 rule in
+ * `AGENTS.md`, applied to the pass with the most arithmetic in it.
+ */
+
+/**
+ * Keeps fragments crossing the resting plane from opening a hairline seam.
+ *
+ * The clip is a plane test on a *displaced* surface, so geometry that touches the waterline
+ * lands on both sides of it by a fraction of a millimetre depending on the wave. Three
+ * centimetres of tolerance keeps the shoreline welded; more than that starts showing the
+ * underside of things standing in the water.
+ */
+const CLIP_TOLERANCE = 0.03;
+
+/**
+ * Stand the camera on the other side of the plane, looking back.
+ *
+ * A mirror across a horizontal plane negates height about it and negates pitch, and leaves yaw
+ * and the lens alone. **The aspect is the target's rather than the canvas's**: a reflection is
+ * rendered at a scale, and projecting it at the canvas's aspect stretches the mirror against
+ * the surface it is sampled onto.
+ */
+export function mirrorCamera(source: Camera, planeY: number, aspect: number, out: Camera): void {
+  out.position[0] = source.position[0] ?? 0;
+  out.position[1] = planeY * 2 - (source.position[1] ?? 0);
+  out.position[2] = source.position[2] ?? 0;
+  out.yaw = source.yaw;
+  out.pitch = -source.pitch;
+  out.fovYDeg = source.fovYDeg;
+  out.near = source.near;
+  out.far = source.far;
+  out.updateMatrices(aspect);
+}
+
+/**
+ * The half-space the mirrored pass may draw, as `dot(vec4(worldPos, 1), plane) >= 0`.
+ *
+ * **A mirror reflects the scene on the viewer's side of the plane**, so which side that is
+ * follows the camera: above water it keeps y ≥ plane, below it keeps y ≤ plane. Deciding it
+ * from a constant instead is a reflection that inverts the moment a swimmer's head goes under.
+ */
+export function reflectionClipPlane(sourceY: number, planeY: number, out: Float32Array): void {
+  const side = sourceY >= planeY ? 1 : -1;
+  out[0] = 0;
+  out[1] = side;
+  out[2] = 0;
+  out[3] = -side * planeY + CLIP_TOLERANCE;
+}
+
+/** How large a reflection target may be, given the drawing buffer and the device's ceiling. */
+export interface ReflectionSize {
+  width: number;
+  height: number;
+}
+
+/**
+ * Size the target, clamped by **one shared factor** rather than per axis.
+ *
+ * Clamping each axis independently squashes the reflection on a drawing buffer wider than the
+ * GPU's texture limit, because the mirror is then rendered at one aspect and sampled at
+ * another. Scaling both by the tighter of the two ratios keeps it square and merely smaller.
+ */
+export function reflectionTargetSize(
+  canvasWidth: number,
+  canvasHeight: number,
+  scale: number,
+  maxTextureSize: number,
+  out: ReflectionSize,
+): ReflectionSize {
+  const targetScale = Math.min(
+    scale,
+    maxTextureSize / Math.max(canvasWidth, 1),
+    maxTextureSize / Math.max(canvasHeight, 1),
+  );
+  out.width = Math.max(Math.round(canvasWidth * targetScale), 1);
+  out.height = Math.max(Math.round(canvasHeight * targetScale), 1);
+  return out;
+}

package/src/render/plumeGeometry.ts

@@ -0,0 +1,75 @@
+import type { PlumePlacement } from './plumeRenderer.ts';
+
+/**
+ * The crossed quads a plume batch is drawn from, built once for both backends.
+ *
+ * **Two blades rather than a billboard, and two rather than three.** A single card turned to
+ * face the viewer has no three-dimensional structure to see — orbiting a fire showed the same
+ * silhouette from every angle — while a fixed cross has the parallax a volume has and never
+ * goes edge-on, because its partner is square-on at that exact moment. The third blade costs
+ * 50% more geometry for a difference the eye does not separate at these sizes.
+ *
+ * Here rather than in `plumeRenderer.ts` because a second copy of a mesh generator is a plume
+ * whose triangles differ per backend, which is the 2026-08-13 rule in `AGENTS.md`.
+ */
+export const PLUME_BLADES = 2;
+export const PLUME_VERTS = PLUME_BLADES * 4;
+
+/** Corners of one blade, as a quad. */
+const CORNERS = [
+  [-1, -1],
+  [1, -1],
+  [1, 1],
+  [-1, 1],
+] as const;
+
+/** The five attribute streams and the index list. */
+export interface PlumeGeometryData {
+  readonly centers: Float32Array;
+  readonly corners: Float32Array;
+  readonly sizes: Float32Array;
+  readonly seeds: Float32Array;
+  readonly blades: Float32Array;
+  readonly indices: Uint32Array;
+}
+
+export function buildPlumeGeometry(plumes: readonly PlumePlacement[]): PlumeGeometryData {
+  const count = plumes.length;
+  const centers = new Float32Array(count * PLUME_VERTS * 3);
+  const corners = new Float32Array(count * PLUME_VERTS * 2);
+  const sizes = new Float32Array(count * PLUME_VERTS * 2);
+  const seeds = new Float32Array(count * PLUME_VERTS);
+  const blades = new Float32Array(count * PLUME_VERTS);
+  const indices = new Uint32Array(count * 6 * PLUME_BLADES);
+
+  for (let f = 0; f < count; f++) {
+    const plume = plumes[f];
+    if (plume === undefined) continue;
+    for (let b = 0; b < PLUME_BLADES; b++) {
+      for (let c = 0; c < 4; c++) {
+        const v = f * PLUME_VERTS + b * 4 + c;
+        const corner = CORNERS[c] ?? [0, 0];
+        centers[v * 3] = plume.x;
+        centers[v * 3 + 1] = plume.y;
+        centers[v * 3 + 2] = plume.z;
+        corners[v * 2] = corner[0];
+        corners[v * 2 + 1] = corner[1];
+        sizes[v * 2] = plume.width;
+        sizes[v * 2 + 1] = plume.height;
+        // Golden-ratio phase offset: neighbours never animate in step.
+        seeds[v] = f * 0.618;
+        // Which blade of the cross this vertex belongs to.
+        blades[v] = b;
+      }
+      const base = f * PLUME_VERTS + b * 4;
+      const i = (f * PLUME_BLADES + b) * 6;
+      indices[i] = base;
+      indices[i + 1] = base + 1;
+      indices[i + 2] = base + 2;
+      indices[i + 3] = base;
+      indices[i + 4] = base + 2;
+      indices[i + 5] = base + 3;
+    }
+  }
+  return { centers, corners, sizes, seeds, blades, indices };
+}

package/src/render/plumeMaterial.ts

@@ -0,0 +1,99 @@
+import { ARCANE_FRAG } from './shaders/arcane.ts';
+import { FIRE_FRAG, PLUME_VERT } from './shaders/fire.ts';
+import { SMOKE_FRAG } from './shaders/smoke.ts';
+import { ARCANE_FRAG_WGSL, ARCANE_BINDINGS } from './shaders/generated/arcane.wgsl.ts';
+import { FIRE_FRAG_WGSL, PLUME_VERT_WGSL, FIRE_BINDINGS } from './shaders/generated/fire.wgsl.ts';
+import { SMOKE_FRAG_WGSL, SMOKE_BINDINGS } from './shaders/generated/smoke.wgsl.ts';
+
+/**
+ * Which plume material a caller wants, by name rather than by source.
+ *
+ * **`PlumeOptions` used to take GLSL strings, and that could not cross to a second backend.**
+ * WebGPU has no runtime GLSL compiler and this package must never ship one — the toolchain is
+ * dev-only, for the licensing and size reasons the WGSL toolchain design
+ * records — so a caller-supplied `vertexSource` was a capability that existed on exactly one
+ * backend and could never exist on the other.
+ *
+ * Naming the material instead makes it universal by construction: each backend resolves the
+ * name to the shader it can actually compile, and neither can be handed something it cannot
+ * use. **The cost is real and was accepted deliberately**: a caller can no longer supply its
+ * own plume shader at all. That capability was documented — `uCameraRight` is set
+ * unconditionally precisely so a caller's own vertex shader could billboard against it — and
+ * it is gone. A world that needs a plume this engine does not ship now needs the engine to
+ * ship it.
+ */
+export type PlumeMaterial = 'fire' | 'smoke' | 'arcane';
+
+/** The two source pairs one material resolves to, one per backend. */
+export interface PlumeShaders {
+  readonly label: string;
+  readonly vertexSource: string;
+  readonly fragmentSource: string;
+  readonly vertexWgsl: string;
+  readonly fragmentWgsl: string;
+  /** What the generator recorded about the fragment stage's uniform block. */
+  readonly fragmentBindings: unknown;
+  readonly vertexBindings: unknown;
+}
+
+/**
+ * Every plume this engine ships, with both compilations of each.
+ *
+ * One table rather than a lookup per backend: a material present in one and absent from the
+ * other is precisely the drift the 2026-08-13 rule in `AGENTS.md` exists to prevent, and here
+ * it would be a plume that draws on WebGL2 and throws on WebGPU.
+ */
+const MATERIALS: Readonly<Record<PlumeMaterial, PlumeShaders>> = {
+  fire: {
+    label: 'plume:fire',
+    vertexSource: PLUME_VERT,
+    fragmentSource: FIRE_FRAG,
+    vertexWgsl: PLUME_VERT_WGSL,
+    fragmentWgsl: FIRE_FRAG_WGSL,
+    vertexBindings: FIRE_BINDINGS.PLUME_VERT,
+    fragmentBindings: FIRE_BINDINGS.FIRE_FRAG,
+  },
+  smoke: {
+    label: 'plume:smoke',
+    vertexSource: PLUME_VERT,
+    fragmentSource: SMOKE_FRAG,
+    vertexWgsl: PLUME_VERT_WGSL,
+    fragmentWgsl: SMOKE_FRAG_WGSL,
+    /* Smoke shares the plume vertex stage; its own file records only the fragment one. */
+    vertexBindings: FIRE_BINDINGS.PLUME_VERT,
+    fragmentBindings: SMOKE_BINDINGS.SMOKE_FRAG,
+  },
+  /*
+   * A radial counter-rotating swirl rather than a rising column, so it reads as a spell
+   * containing a thing rather than as a fire underneath it.
+   *
+   * **Added because a consumer already drew with it.** The shader has existed here since
+   * before the second backend and a consumer passed it as `ARCANE_FRAG`, which the move to
+   * named materials took away with nothing to replace it — the one effect in either consumer
+   * that the material table did not already cover. It is the only material that reads
+   * `uTint`, and that is why: an aura takes the day's glow colour, so relics shift with the
+   * palette exactly as the lamps do.
+   */
+  arcane: {
+    label: 'plume:arcane',
+    vertexSource: PLUME_VERT,
+    fragmentSource: ARCANE_FRAG,
+    vertexWgsl: PLUME_VERT_WGSL,
+    fragmentWgsl: ARCANE_FRAG_WGSL,
+    /* Arcane shares the plume vertex stage; its own file records only the fragment one. */
+    vertexBindings: FIRE_BINDINGS.PLUME_VERT,
+    fragmentBindings: ARCANE_BINDINGS.ARCANE_FRAG,
+  },
+};
+
+/** Resolve a material name, or say which names exist. */
+export function plumeShaders(material: PlumeMaterial): PlumeShaders {
+  const found = MATERIALS[material];
+  if (found === undefined) {
+    throw new Error(
+      `createPlumes: unknown plume material "${String(material)}". ` +
+        `Known materials: ${Object.keys(MATERIALS).join(', ')}.`,
+    );
+  }
+  return found;
+}

package/src/render/plumeRenderer.ts

@@ -0,0 +1,272 @@
+import { PLUME_VERTS } from './plumeGeometry.ts';
+import type { FrameView } from './frameView.ts';
+import { compileProgram, uniformLocations } from './shader.ts';
+import { bindAtmosphere } from './atmosphere.ts';
+import { plumeShaders, type PlumeMaterial } from './plumeMaterial.ts';
+import { buildPlumeGeometry } from './plumeGeometry.ts';
+import type { Atmosphere } from './atmosphere.ts';
+import type { Vec3 } from '../math/color.ts';
+
+/**
+ * Batched camera-facing quads for volumetric effects — flames, smoke, steam,
+ * dust. Game-agnostic: it knows positions, sizes and time, and nothing about
+ * what the plume represents.
+ *
+ * One VAO for the whole batch, four vertices per plume, everything animated on
+ * the GPU. The caller supplies the shader pair, so a new effect is a new
+ * fragment shader rather than a new renderer.
+ */
+export interface PlumePlacement {
+  x: number;
+  y: number;
+  z: number;
+  /** Half-width and full height, metres. */
+  width: number;
+  height: number;
+}
+
+export type PlumeBlend = 'additive' | 'alpha';
+
+export interface PlumeOptions {
+  /**
+   * Which plume this is, by name.
+   *
+   * **This replaced a pair of GLSL source strings on 2026-08-13, and the replacement is a
+   * breaking change made on purpose.** A caller-supplied shader is a capability that can only
+   * ever exist on WebGL2: WebGPU has no runtime GLSL compiler and this package must not ship
+   * one. Naming the material lets each backend resolve what it can compile. See
+   * `plumeMaterial.ts` for what was given up.
+   */
+  material: PlumeMaterial;
+  /** Emissive effects (fire) add light; dense ones (smoke) occlude it. */
+  blend: PlumeBlend;
+  /**
+   * How much the quads swell and shrink over time, 0 for a fixed size. Purely
+   * visual — anything gameplay depends on must keep its own fixed volume, or
+   * the simulation starts depending on the render clock.
+   */
+  sizePulse?: number;
+  /**
+   * How far this plume leans in a given wind, metres per m/s at its crown.
+   * Smoke is carried; a flame is anchored to its fuel and barely bends.
+   */
+  windResponse?: number;
+  /**
+   * Colour handed to the fragment stage as `uTint`, or white when absent.
+   *
+   * Optional shader contract, the same arrangement `uNoiseOctaves` and
+   * `uCameraRight` already use: the uniform is set unconditionally and
+   * `uniformLocations` hands back null for a shader that ignores it, so `fire`
+   * and `smoke` are untouched by this existing.
+   */
+  tint?: Vec3;
+}
+
+/**
+ * Blades in each plume's cross, and the vertices that costs.
+ *
+ * **Two, crossed at 90°, instead of one card turned to face the viewer.** A single
+ * billboard has no three-dimensional structure to see: orbiting a fire showed the
+ * identical silhouette from every angle, because every card shared one camera-derived
+ * axis and the whole plume swivelled as a sheet. Reported twice: the fire did not read
+ * as three-dimensional, it read as something that moved with the camera — and after a
+ * first attempt that only *leaned* edge-on cards toward the viewer, it still did,
+ * correctly, because leaning still rotates whichever cards are edge-on, so the ensemble
+ * still tracks the viewer.
+ *
+ * A cross cannot track anything: both blades are fixed in world space, so turning
+ * around a fire genuinely brings one broadside as the other goes edge-on, which is
+ * the parallax a volume has. It also removes the reason billboarding existed — a
+ * blade going edge-on no longer vanishes, because its partner is square-on at that
+ * exact moment.
+ *
+ * Two rather than three because the plumes blend additively and are drawn in
+ * quantity: the third blade costs 50% more geometry for a difference the eye does not
+ * separate at the sizes these are drawn.
+ */
+const BLADES = 2;
+/* The shared count, so both backends step a plume's vertices the same way. */
+const VERTS_PER_PLUME = PLUME_VERTS;
+
+const CORNERS = [
+  [-1, -1],
+  [1, -1],
+  [1, 1],
+  [-1, 1],
+] as const;
+
+export class PlumeRenderer {
+  private readonly program: WebGLProgram;
+  private readonly uniforms: Record<string, WebGLUniformLocation>;
+  private readonly vao: WebGLVertexArrayObject;
+  private readonly buffers: WebGLBuffer[] = [];
+  private readonly indexCount: number;
+  /**
+   * The per-vertex size buffer, kept so a caller can turn individual plumes off.
+   *
+   * A batch is uploaded once because a fire does not move — but a *fire that is not always
+   * burning* does need saying. Oil slicks ignite on a cycle, and before this there was no way
+   * to draw one only while it was alight: the launch happened with an empty screen.
+   */
+  private readonly sizeBuffer: WebGLBuffer;
+  private readonly sizes: Float32Array;
+  private readonly baseSizes: Float32Array;
+  private readonly blend: PlumeBlend;
+  private readonly sizePulse: number;
+  private readonly windResponse: number;
+  private readonly noiseOctaves: number;
+  private readonly tint: Vec3;
+
+  constructor(
+    gl: WebGL2RenderingContext,
+    plumes: readonly PlumePlacement[],
+    options: PlumeOptions,
+    noiseOctaves: number,
+  ) {
+    const shaders = plumeShaders(options.material);
+    this.program = compileProgram(gl, shaders.vertexSource, shaders.fragmentSource, shaders.label);
+    this.uniforms = uniformLocations(gl, this.program, 'plumeRenderer');
+    this.blend = options.blend;
+    this.sizePulse = options.sizePulse ?? 0;
+    this.windResponse = options.windResponse ?? 0;
+    this.noiseOctaves = noiseOctaves;
+    this.tint = options.tint ?? [1, 1, 1];
+
+    /* Built in `plumeGeometry.ts`, so both backends lay out the same crossed quads. */
+    const { centers, corners, sizes, seeds, blades, indices } = buildPlumeGeometry(plumes);
+    this.indexCount = indices.length;
+
+    const vao = gl.createVertexArray();
+    if (vao === null) throw new Error(`${shaders.label}: createVertexArray failed`);
+    this.vao = vao;
+    gl.bindVertexArray(vao);
+    this.attach(gl, 0, centers, 3, shaders.label);
+    this.attach(gl, 1, corners, 2, shaders.label);
+    this.sizeBuffer = this.attach(gl, 2, sizes, 2, shaders.label);
+    this.attach(gl, 3, seeds, 1, shaders.label);
+    this.attach(gl, 4, blades, 1, shaders.label);
+    this.sizes = sizes;
+    // The authored sizes, so a hidden plume can be restored to exactly what it was.
+    this.baseSizes = new Float32Array(plumes.length * 2);
+    for (let f = 0; f < plumes.length; f++) {
+      const plume = plumes[f];
+      if (plume === undefined) continue;
+      this.baseSizes[f * 2] = plume.width;
+      this.baseSizes[f * 2 + 1] = plume.height;
+    }
+
+    const indexBuffer = gl.createBuffer();
+    if (indexBuffer === null) throw new Error(`${shaders.label}: createBuffer failed`);
+    this.buffers.push(indexBuffer);
+    gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
+    gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, indices, gl.STATIC_DRAW);
+    gl.bindVertexArray(null);
+  }
+
+  /**
+   * Scale one plume, 0 to hide it.
+   *
+   * Writes only that plume's own vertices — every blade of its cross — so turning a slick's
+   * fire on costs a handful of floats rather than a re-upload of the batch. The caller owns
+   * *when*; the renderer has no idea what a slick is.
+   */
+  setScale(gl: WebGL2RenderingContext, index: number, scale: number): void {
+    const span = VERTS_PER_PLUME * 2;
+    const base = index * span;
+    if (base < 0 || base + span > this.sizes.length) return;
+    const width = this.baseSizes[index * 2] ?? 0;
+    const height = this.baseSizes[index * 2 + 1] ?? 0;
+    for (let c = 0; c < VERTS_PER_PLUME; c++) {
+      this.sizes[base + c * 2] = width * scale;
+      this.sizes[base + c * 2 + 1] = height * scale;
+    }
+    gl.bindBuffer(gl.ARRAY_BUFFER, this.sizeBuffer);
+    gl.bufferSubData(gl.ARRAY_BUFFER, base * 4, this.sizes.subarray(base, base + span));
+  }
+
+  /**
+   * Draw the batch. Call after the sky: these blend without writing depth, and
+   * the sky at depth 1.0 under LEQUAL would otherwise overwrite anything drawn
+   * against open background.
+   */
+  draw(
+    gl: WebGL2RenderingContext,
+    camera: FrameView,
+    timeSeconds: number,
+    atmosphere: Atmosphere,
+    underwaterEnabled: boolean,
+    atmosphereCameraY: number,
+    clipPlane: Float32Array | null,
+    windX = 0,
+    windZ = 0,
+    originX = 0,
+    originY = 0,
+    originZ = 0,
+  ): void {
+    if (this.indexCount === 0) return;
+    const u = this.uniforms;
+
+    gl.useProgram(this.program);
+    gl.uniform2f(u['uWind'] ?? null, windX, windZ);
+    gl.uniform3f(u['uOrigin'] ?? null, originX, originY, originZ);
+    gl.uniform1f(u['uWindResponse'] ?? null, this.windResponse);
+    gl.uniformMatrix4fv(u['uViewProj'] ?? null, false, camera.viewProjection);
+    const v = camera.view;
+    /*
+     * The camera's own basis, for shader pairs that billboard. The plume shaders
+     * shipped here no longer do — they draw world-fixed crosses, because anything
+     * that rotates with the camera reads as flat (see `BLADES`) — but the uniform is
+     * part of the generic contract a caller may supply its own vertex shader against,
+     * and `uniformLocations` hands back null for a shader that ignores it.
+     */
+    gl.uniform3f(u['uCameraRight'] ?? null, v[0] ?? 1, v[4] ?? 0, v[8] ?? 0);
+    gl.uniform3f(u['uCameraUp'] ?? null, v[1] ?? 0, v[5] ?? 1, v[9] ?? 0);
+    gl.uniform3fv(u['uCameraPos'] ?? null, camera.position);
+    gl.uniform1f(u['uTime'] ?? null, timeSeconds);
+    gl.uniform1f(u['uSizePulse'] ?? null, this.sizePulse);
+    // Optional shader contract: generic plume shaders may ignore these uniforms.
+    gl.uniform1i(u['uNoiseOctaves'] ?? null, this.noiseOctaves);
+    gl.uniform3f(u['uTint'] ?? null, this.tint[0], this.tint[1], this.tint[2]);
+    gl.uniform1i(u['uClipEnabled'] ?? null, clipPlane === null ? 0 : 1);
+    if (clipPlane !== null) gl.uniform4fv(u['uClipPlane'] ?? null, clipPlane);
+    bindAtmosphere(gl, u, atmosphere, atmosphereCameraY, underwaterEnabled);
+
+    gl.enable(gl.BLEND);
+    if (this.blend === 'additive') gl.blendFunc(gl.SRC_ALPHA, gl.ONE);
+    else gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+    gl.depthMask(false);
+    gl.disable(gl.CULL_FACE);
+
+    gl.bindVertexArray(this.vao);
+    gl.drawElements(gl.TRIANGLES, this.indexCount, gl.UNSIGNED_INT, 0);
+    gl.bindVertexArray(null);
+
+    gl.enable(gl.CULL_FACE);
+    gl.depthMask(true);
+    gl.disable(gl.BLEND);
+  }
+
+  dispose(gl: WebGL2RenderingContext): void {
+    for (const buffer of this.buffers) gl.deleteBuffer(buffer);
+    gl.deleteVertexArray(this.vao);
+    gl.deleteProgram(this.program);
+  }
+
+  /** Uploads one attribute and returns its buffer, for the rare one a caller can change. */
+  private attach(
+    gl: WebGL2RenderingContext,
+    location: number,
+    data: Float32Array,
+    size: number,
+    label: string,
+  ): WebGLBuffer {
+    const buffer = gl.createBuffer();
+    if (buffer === null) throw new Error(`${label}: createBuffer failed`);
+    this.buffers.push(buffer);
+    gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+    gl.bufferData(gl.ARRAY_BUFFER, data, gl.DYNAMIC_DRAW);
+    gl.enableVertexAttribArray(location);
+    gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+    return buffer;
+  }
+}