@driftengine/core 3.61.0

package/src/render/visibility.ts

@@ -0,0 +1,56 @@
+import type { ReadonlyMat4 } from 'gl-matrix';
+
+import type { Bounds } from '../math/bounds.ts';
+import { sphereInFrustum } from '../math/frustum.ts';
+import type { Frustum } from '../math/frustum.ts';
+
+/**
+ * Whether a mesh placed by a model matrix is anywhere inside a frustum.
+ *
+ * Shared by both backends rather than written twice, for the reason the resource table is: two
+ * copies of a decision are two chances to answer it differently, and a culling disagreement
+ * between backends is an object that is present on one and missing on the other.
+ *
+ * **Scale is the trap, and it is why this is not two lines at each call site.** A bounding sphere
+ * put through a scaling matrix is a sphere of a different size, so the world radius is the local
+ * radius times the *largest* of the three axis scales. Taking the average, or the x scale, or
+ * forgetting entirely, culls an enlarged object while it is plainly on screen — and the failure
+ * looks like a threshold to tune rather than a factor that is missing.
+ *
+ * Non-uniform scale makes the transformed shape an ellipsoid, and the largest axis is the sphere
+ * that contains it. Conservative, which is the only direction a cull may err in.
+ *
+ * Allocates nothing.
+ */
+export function boundsVisible(frustum: Frustum, bounds: Bounds, model: ReadonlyMat4): boolean {
+  const cx = bounds.centre[0] ?? 0;
+  const cy = bounds.centre[1] ?? 0;
+  const cz = bounds.centre[2] ?? 0;
+
+  /* The centre through the model matrix. Column-major, so a column is four consecutive entries. */
+  const m0 = model[0] ?? 0;
+  const m1 = model[1] ?? 0;
+  const m2 = model[2] ?? 0;
+  const m4 = model[4] ?? 0;
+  const m5 = model[5] ?? 0;
+  const m6 = model[6] ?? 0;
+  const m8 = model[8] ?? 0;
+  const m9 = model[9] ?? 0;
+  const m10 = model[10] ?? 0;
+
+  const x = m0 * cx + m4 * cy + m8 * cz + (model[12] ?? 0);
+  const y = m1 * cx + m5 * cy + m9 * cz + (model[13] ?? 0);
+  const z = m2 * cx + m6 * cy + m10 * cz + (model[14] ?? 0);
+
+  /*
+   * The length of each basis vector is that axis' scale, rotation included: a rotation preserves
+   * length, so this reads the scale out of a matrix that also rotates without having to
+   * decompose it.
+   */
+  const sx = Math.sqrt(m0 * m0 + m1 * m1 + m2 * m2);
+  const sy = Math.sqrt(m4 * m4 + m5 * m5 + m6 * m6);
+  const sz = Math.sqrt(m8 * m8 + m9 * m9 + m10 * m10);
+  const radius = bounds.radius * Math.max(sx, sy, sz);
+
+  return sphereInFrustum(frustum, x, y, z, radius);
+}

package/src/render/waterDraw.ts

@@ -0,0 +1,167 @@
+import type { Vec3 } from '../math/color.ts';
+import { seaStateForAgitation, seaStateForWind } from './seaState.ts';
+/* Type-only, so the cycle back to `waterRenderer` is erased rather than real. */
+import type { WaterBody } from './waterRenderer.ts';
+
+/**
+ * Where the sheet is laid and how hard it is blowing on it, decided for both backends.
+ *
+ * **The interesting half of `WaterRenderer.draw` is arithmetic, not binding.** Snapping the
+ * ocean to whole cells, choosing a sea state from the wind or from an authored agitation,
+ * falling back to a bearing in a dead calm — each is a rule with a reason, and a second copy
+ * of any of them is a sea that behaves differently depending on which backend drew it. That is
+ * the 2026-08-13 rule in `AGENTS.md`.
+ */
+
+/**
+ * Everything the water shader needs that is not a colour, a matrix or the medium.
+ *
+ * **The three extents are pairs, and were single numbers until 2026-08-28.** A body bounded by one
+ * number is a square, and the shape a consumer actually has is a channel: long in one axis, narrow
+ * in the other. Each is measured along the body's **own** axes, which `forward` then turns into the
+ * world — so the rim and the wave fade follow the rectangle however it is laid, and the ocean passes
+ * the same number twice and is unchanged.
+ */
+export interface ResolvedWater {
+  /** Where the sheet is centred: snapped under the camera, or the body's own middle. */
+  readonly origin: Float32Array;
+  /** Metres per unit of the sheet's own grid, per axis. The ocean's grid is metres, so (1, 1). */
+  readonly span: Float32Array;
+  /** How far the sheet carries out, per axis. */
+  readonly half: Float32Array;
+  /** What the wave fade is measured against, so a bowl is flat at its rim. */
+  readonly nearHalf: Float32Array;
+  /** The body's own +z in world XZ, unit length. (0, 1) for anything unturned. */
+  readonly forward: Float32Array;
+  /** Unit wind bearing, or the authored fallback in a dead calm. */
+  readonly windDir: Float32Array;
+  waveGain: number;
+  foamGain: number;
+  /** Whether this body is a bounded patch rather than the ocean. */
+  bounded: boolean;
+}
+
+export function createResolvedWater(): ResolvedWater {
+  return {
+    origin: new Float32Array(2),
+    span: new Float32Array([1, 1]),
+    half: new Float32Array(2),
+    nearHalf: new Float32Array(2),
+    forward: new Float32Array([0, 1]),
+    windDir: new Float32Array([1, 0]),
+    waveGain: 0,
+    foamGain: 0,
+    bounded: false,
+  };
+}
+
+/**
+ * Lay the sheet and settle the sea, into a target the caller owns.
+ *
+ * `cellSize`, `nearHalfExtent` and `farHalfExtent` come from the grid the renderer built, so
+ * they differ per renderer rather than being global — which is why they are arguments.
+ */
+export function resolveWater(
+  settings: WaterBody,
+  cameraX: number,
+  cameraZ: number,
+  cellSize: number,
+  nearHalfExtent: number,
+  farHalfExtent: number,
+  windX: number,
+  windZ: number,
+  out: ResolvedWater,
+): ResolvedWater {
+  const bounds = settings.bounds;
+  out.bounded = bounds !== undefined;
+  if (bounds === undefined) {
+    /*
+     * Snapped to whole cells. Anything else re-samples the wave field as the camera moves,
+     * which reads as the surface swimming rather than as the camera travelling over it.
+     */
+    out.origin[0] = Math.floor(cameraX / cellSize) * cellSize;
+    out.origin[1] = Math.floor(cameraZ / cellSize) * cellSize;
+    out.span[0] = 1;
+    out.span[1] = 1;
+    out.half[0] = farHalfExtent;
+    out.half[1] = farHalfExtent;
+    out.nearHalf[0] = nearHalfExtent;
+    out.nearHalf[1] = nearHalfExtent;
+    out.forward[0] = 0;
+    out.forward[1] = 1;
+  } else {
+    out.origin[0] = bounds.centreX;
+    out.origin[1] = bounds.centreZ;
+    /*
+     * **`halfM` is the square shorthand and a per-axis extent overrides it on that axis alone.**
+     * The rule is applied here and nowhere else, which is what makes two spellings of a square
+     * affordable: a second place resolving them is where they would begin to disagree. A body given
+     * none of the three is zero-sized and draws nothing, which is a defined state and the right
+     * one — the other reading of "no extent" is the unbounded ocean, and omitting `bounds` already
+     * says that.
+     */
+    const halfX = bounds.halfX ?? bounds.halfM ?? 0;
+    const halfZ = bounds.halfZ ?? bounds.halfM ?? 0;
+    out.span[0] = halfX;
+    out.span[1] = halfZ;
+    out.half[0] = halfX;
+    out.half[1] = halfZ;
+    /* The wave fade measures against this, so a bounded body is flat at its own rim. */
+    out.nearHalf[0] = halfX;
+    out.nearHalf[1] = halfZ;
+    /*
+     * The direction the body's own +z takes, normalised here so that no backend has to.
+     *
+     * A direction of no length is read as unturned instead of divided by: the basis the shader
+     * builds from this places every vertex of the sheet, so a NaN here is not a wrong sheet, it is
+     * a sheet that is nowhere. `Math.sqrt` and not `Math.hypot`, as everywhere else here.
+     */
+    const fx = bounds.forwardX ?? 0;
+    const fz = bounds.forwardZ ?? 1;
+    const length = Math.sqrt(fx * fx + fz * fz);
+    out.forward[0] = length > 1e-6 ? fx / length : 0;
+    out.forward[1] = length > 1e-6 ? fz / length : 1;
+  }
+
+  const windSpeed = Math.hypot(windX, windZ);
+  /*
+   * **`agitation` is an override, not an addition.** Wind builds waves, which is right under
+   * the sky and wrong for a cistern, a flooded corridor or a tank below deck — those have a
+   * surface that moves with no wind to explain it, and tying them to the weather means a gale
+   * outside makes the water in a sealed room choppy.
+   */
+  const sea =
+    settings.agitation === undefined
+      ? seaStateForWind(windSpeed)
+      : seaStateForAgitation(settings.agitation);
+  const inv = windSpeed > 1e-5 ? 1 / windSpeed : 0;
+  /* Falls back to the authored bearing in a dead calm rather than collapsing every wave
+     direction onto zero. */
+  out.windDir[0] = inv === 0 ? 1 : windX * inv;
+  out.windDir[1] = inv === 0 ? 0 : windZ * inv;
+  out.waveGain = sea.steepness * (settings.waveScale ?? 1);
+  out.foamGain = sea.foam;
+  return out;
+}
+
+/** The body's own colours and scalars, read the same way by both backends. */
+export interface WaterAppearance {
+  readonly deepColor: Vec3;
+  readonly shallowColor: Vec3;
+  readonly level: number;
+  readonly nadirOpacity: number;
+  readonly visibility: number;
+  readonly mirror: number;
+}
+
+/** Defaults applied once, so neither backend invents its own. */
+export function waterAppearance(settings: WaterBody): WaterAppearance {
+  return {
+    deepColor: settings.deepColor,
+    shallowColor: settings.shallowColor,
+    level: settings.level,
+    nadirOpacity: settings.density ?? 0.22,
+    visibility: settings.visibility ?? 1,
+    mirror: settings.mirror ?? 0,
+  };
+}

package/src/render/waterGrid.ts

@@ -0,0 +1,180 @@
+/**
+ * The ocean's tessellation: a near sheet that carries waves, and a ringed skirt
+ * that carries distance.
+ *
+ * These are two different problems and one mesh cannot serve both.
+ *
+ * The near sheet must be *uniform* and snapped to whole cells. That combination
+ * is what makes the wave lattice invariant in world space: shifting by exactly
+ * one cell lands every vertex where its neighbour was, so the reconstructed
+ * surface does not change as the camera moves. Break the uniformity — grade the
+ * cells to buy reach, say — and that invariance goes with it. Cells wider than
+ * the snap quantum are re-sampled at a new phase on every snap, and the surface
+ * visibly swims underfoot.
+ *
+ * The skirt carries no displacement, so its tessellation cannot distort
+ * anything, and it can stretch to tens of kilometres. That reach is not
+ * decoration: a sheet that stops short ends in a straight line with a corner in
+ * it, and no alpha ramp hides that. At eye height the horizon of a flat plane is
+ * at infinity, so a fade measured in world metres compresses into a pixel or two
+ * of skyline and the corner survives. The rim has to be too small to resolve.
+ *
+ * But the skirt cannot be a single leap to the far edge either, even though its
+ * *shape* would be identical. Fog is evaluated per fragment from world position,
+ * so one triangle spanning 150 m to 30 km squeezes the entire fog gradient into
+ * the handful of pixels that triangle covers — which puts a hard line right back
+ * at the near sheet's rim, in exactly the place the skirt was meant to hide. So
+ * the skirt is a set of concentric rings whose radii grow geometrically, giving
+ * the gradient somewhere to happen. They are cheap: being flat, they need only
+ * enough vertices per side to stay a square.
+ */
+
+/** Concentric rings between the near sheet and the far edge. */
+const SKIRT_RINGS = 12;
+/** Vertices per side of each ring. A flat square needs very few. */
+const SKIRT_SEGMENTS_PER_SIDE = 8;
+
+export interface WaterGrid {
+  /** Grid-local xz pairs, metres from the camera-snapped origin. */
+  readonly offsets: Float32Array;
+  readonly indices: Uint32Array;
+  /**
+   * Cell size of the near sheet. The grid origin snaps to whole multiples of
+   * this — see above for why that must equal the cell size exactly.
+   */
+  readonly cellSize: number;
+  /** Half-width of the wave-bearing near sheet. */
+  readonly nearHalfExtent: number;
+  /** Half-width of the outermost ring, i.e. how far the ocean reaches. */
+  readonly farHalfExtent: number;
+}
+
+/**
+ * Point at parameter `t` (in [0, 4)) around a square of the given half-width,
+ * walked anticlockwise from the -x/-z corner. Consistent ordering across rings
+ * is what lets consecutive rings be stitched by index arithmetic alone.
+ */
+function squarePerimeter(t: number, radius: number): [number, number] {
+  const side = Math.floor(t) % 4;
+  const u = t - Math.floor(t);
+  const span = radius * 2;
+  if (side === 0) return [-radius + span * u, -radius];
+  if (side === 1) return [radius, -radius + span * u];
+  if (side === 2) return [radius - span * u, radius];
+  return [-radius, radius - span * u];
+}
+
+export function buildWaterGrid(
+  resolution: number,
+  nearExtent: number,
+  farHalfExtent: number,
+): WaterGrid {
+  const side = resolution + 1;
+  const cellSize = nearExtent / resolution;
+  const nearHalfExtent = nearExtent * 0.5;
+
+  const perimeter = SKIRT_SEGMENTS_PER_SIDE * 4;
+  const nearVertices = side * side;
+  const skirtVertices = (SKIRT_RINGS + 1) * perimeter;
+  const offsets = new Float32Array((nearVertices + skirtVertices) * 2);
+
+  for (let z = 0; z < side; z++) {
+    const gz = z * cellSize - nearHalfExtent;
+    for (let x = 0; x < side; x++) {
+      const v = (z * side + x) * 2;
+      offsets[v] = x * cellSize - nearHalfExtent;
+      offsets[v + 1] = gz;
+    }
+  }
+
+  // Geometric radii: each ring is the same factor wider than the last, so the
+  // fog gradient gets roughly equal screen space in every band.
+  const growth = (farHalfExtent / nearHalfExtent) ** (1 / SKIRT_RINGS);
+  for (let ring = 0; ring <= SKIRT_RINGS; ring++) {
+    const radius = ring === SKIRT_RINGS ? farHalfExtent : nearHalfExtent * growth ** ring;
+    for (let i = 0; i < perimeter; i++) {
+      const [px, pz] = squarePerimeter(i / SKIRT_SEGMENTS_PER_SIDE, radius);
+      const v = (nearVertices + ring * perimeter + i) * 2;
+      offsets[v] = px;
+      offsets[v + 1] = pz;
+    }
+  }
+
+  const indices = new Uint32Array(resolution * resolution * 6 + SKIRT_RINGS * perimeter * 6);
+  let i = 0;
+  for (let z = 0; z < resolution; z++) {
+    for (let x = 0; x < resolution; x++) {
+      const a = z * side + x;
+      const b = a + 1;
+      const c = a + side;
+      const d = c + 1;
+      indices[i++] = a;
+      indices[i++] = c;
+      indices[i++] = b;
+      indices[i++] = b;
+      indices[i++] = c;
+      indices[i++] = d;
+    }
+  }
+  for (let ring = 0; ring < SKIRT_RINGS; ring++) {
+    const inner = nearVertices + ring * perimeter;
+    const outer = inner + perimeter;
+    for (let k = 0; k < perimeter; k++) {
+      const next = (k + 1) % perimeter;
+      indices[i++] = inner + k;
+      indices[i++] = outer + k;
+      indices[i++] = inner + next;
+      indices[i++] = inner + next;
+      indices[i++] = outer + k;
+      indices[i++] = outer + next;
+    }
+  }
+
+  return { offsets, indices, cellSize, nearHalfExtent, farHalfExtent };
+}
+
+/**
+ * Cells per side of the bounded-body patch.
+ *
+ * Exported so neither backend keeps its own copy: a patch built at two resolutions is two
+ * different meshes for the same pool, and nothing would raise.
+ */
+export const PATCH_RESOLUTION = 24;
+
+/**
+ * A flat square sheet in [-1, 1], for any body of water with edges.
+ *
+ * Here rather than in `waterRenderer.ts` because both backends build the same patch, and a
+ * second copy of a mesh generator is a bounded body whose triangles differ per backend.
+ */
+export function buildUnitSheet(resolution: number): {
+  offsets: Float32Array;
+  indices: Uint32Array;
+} {
+  const side = resolution + 1;
+  const offsets = new Float32Array(side * side * 2);
+  let v = 0;
+  for (let z = 0; z < side; z++) {
+    for (let x = 0; x < side; x++) {
+      offsets[v++] = (x / resolution) * 2 - 1;
+      offsets[v++] = (z / resolution) * 2 - 1;
+    }
+  }
+  const indices = new Uint32Array(resolution * resolution * 6);
+  let i = 0;
+  for (let z = 0; z < resolution; z++) {
+    for (let x = 0; x < resolution; x++) {
+      const a = z * side + x;
+      const b = a + 1;
+      const c = a + side;
+      const d = c + 1;
+      indices[i++] = a;
+      indices[i++] = c;
+      indices[i++] = b;
+      indices[i++] = b;
+      indices[i++] = c;
+      indices[i++] = d;
+    }
+  }
+  return { offsets, indices };
+}