@driftengine/terrain 3.61.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Drift Technologies
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,9 @@
+DriftEngine
+Copyright 2026 Drift Technologies
+
+This product includes software developed at Drift Technologies
+(https://github.com/drftrun/driftengine).
+
+Licensed under the Apache License, Version 2.0. Section 4(d) of that licence
+requires this NOTICE to be reproduced in any derivative work you distribute,
+in the source, the documentation, or a display generated by the work.

package/README.md

@@ -0,0 +1,166 @@
+# @driftengine/terrain
+
+A heightfield, the geometry it draws, and the same answer to both.
+
+**Cost: 1.4 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it
+drifts more than 3% — the number is derived from the same floors that gate asserts, so a README
+quoting a stale one is a red suite rather than a thing somebody notices.
+
+## What it is
+
+```ts
+import { Terrain, heightfieldPatch } from '@driftengine/terrain';
+
+const terrain = new Terrain({
+  width: 257,
+  depth: 257,
+  spacingM: 2,
+  heights, // 257 * 257 metres, row-major, x fastest
+  origin: [-256, 0, -256],
+});
+
+const near = renderer.createMesh(heightfieldPatch(terrain, { x: 0, z: 0, cells: 32 }));
+const far = renderer.createMesh(
+  heightfieldPatch(terrain, { x: 32, z: 0, cells: 32, step: 4, neighbours: { minusX: 1 } }),
+);
+```
+
+**It imports no renderer.** What comes back is `MeshData`, which goes to `createMesh` like any other
+geometry, so terrain is drawn by the pass that already exists. That is why this is a package rather
+than a part of core: a world with no terrain pays nothing, and a world with terrain pays for
+arithmetic.
+
+## The query answers the surface that is drawn
+
+`terrain.heightAt(x, z)` reads the **triangle** the point falls in, not a bilinear patch through the
+four samples around it. Those are different surfaces — they agree only at the corners and along the
+diagonal they share — and the bilinear one is the obvious thing to write.
+
+Writing it puts a character above the ground over half of every cell and below it over the other
+half, by up to a quarter of that cell's height range, everywhere, for ever. There is no screenshot
+that shows it and no test that fails. So the query reads the triangulation, `heightfieldPatch` emits
+that same triangulation, and a test asserts every vertex of a patch against the query.
+
+`terrain.normalAt(x, z, out)` is the other way round on purpose: a central difference over the
+samples, so it is continuous across every cell boundary. A face normal jumps at every edge, which
+makes terrain faceted and — worse — makes two patches shade differently along the edge they share,
+which reads as a crack in geometry that has none. A caller who wants the plane a wheel rests on
+takes three `heightAt` samples; a caller orienting a character takes this.
+
+## The seam between two levels of detail is matched, not hidden
+
+A heightfield drawn at one resolution is either too coarse underfoot or too fine at the horizon, so
+it is drawn in patches and the distant ones skip samples with `step`. Where a patch that skips none
+meets one that skips every other, the fine edge has vertices the coarse edge does not — and those
+sit on the field while the coarse edge cuts the chord beneath them. **The gap is a crack, and a
+crack in terrain is a hole through to the sky.**
+
+The usual remedy is a skirt: a vertical curtain dropped from every patch edge, which fills the hole
+with something the wrong colour, lit the wrong way, and costs geometry along every boundary in the
+world for ever.
+
+`neighbours` does it exactly instead. Name the step of any neighbour that is **coarser** than this
+patch, and the fine edge's odd vertices move onto the coarse edge's own straight segment, so the two
+edges are one polyline and there is nothing to fill:
+
+```ts
+heightfieldPatch(terrain, { x: 32, z: 0, cells: 32, step: 1, neighbours: { plusX: 4 } });
+```
+
+Only the coarser side needs naming — the finer patch is the one that moves — so a caller passes what
+it knows and leaves the rest out.
+
+**What it costs, stated because it is real:** along a matched edge the drawn surface is the coarse
+chord rather than the field, so `heightAt` and the picture differ there by up to the sag of one
+coarse cell. That is the same error the coarse patch carries over its whole area, arriving one cell
+early.
+
+## Several materials across one field
+
+```ts
+const materials = new TerrainMaterials({
+  materials: [{ color: [0.3, 0.5, 0.2] }, { color: [0.5, 0.5, 0.5], specular: 0.3 }],
+  width: 64,
+  depth: 64,
+  weights, // 64 * 64 * 2, row-major, material fastest
+});
+
+heightfieldPatch(terrain, { x: 0, z: 0, cells: 32, materials });
+```
+
+**A weight map baked into vertex colour, and that is the idiomatic answer here rather than a
+compromise.** This engine's colour _is_ vertex data — it is what makes the world one flat-shaded
+draw call. A splat map read by a shader would mean a texture bound on every terrain draw and a
+branch in `flatFrag`, which Track D measured at 19.8 KB gzipped for a capability generated into
+sixteen fragment permutations. This costs nothing at runtime: the blend happens once, where the
+patch is built.
+
+**What that gives up**: the blend is only as sharp as the mesh. A material boundary inside a cell is
+drawn as a gradient across it, and a patch at a quarter detail blends four times as coarsely. A
+consumer who wants a sharp line — a road edge, a cliff base — draws that patch at full detail, which
+is the same dial the geometry already uses.
+
+**The weights are read bilinearly, which is the opposite of how a height is read**, and both
+decisions are written down because the contrast is the point. A height is read as the _triangle_
+because the surface is drawn as triangles and the query has to agree with the picture. A weight is
+not drawn at all: it decides a vertex colour, and the vertex is wherever the mesh put it. Reading a
+weight map as triangles would put a visible crease along every cell diagonal for nothing.
+
+Weights are normalised and a sample that weighs nothing falls back to the first material, because an
+unpainted corner of a map should not be a black patch.
+
+## It collides, through the mesh the picture is made of
+
+```ts
+import { meshShape, BODY_STATIC } from '@driftengine/physics';
+
+const patch = heightfieldPatch(terrain, { x: 0, z: 0, cells: 32 });
+world.addBody({ type: BODY_STATIC, shape: meshShape(patch.positions, patch.indices) });
+```
+
+There is no terrain-shaped collider and none is needed for terrain to collide: `meshShape` takes
+exactly the two arrays a patch hands back, so **the geometry you draw is the geometry you collide
+with**, with nothing authored twice. `terrainCollision.test.ts` asserts the three surfaces are one:
+a ray cast against that body lands where `heightAt` says the ground is, at forty points off the
+lattice.
+
+That test is also what found a real defect in the first version of this package — the mesh was split
+along one diagonal while the query read the other, which every per-vertex assertion passed because a
+vertex lies on both.
+
+**A patch drawn coarse collides coarse**, which is the right answer: colliding against the field
+while drawing a chord would let a character walk through ground they can see.
+
+## From a script
+
+`drift/terrain` is bound: `heightAt`, `normalX`/`normalY`/`normalZ`, `slopeAt`, `covers`,
+`extentX` and `extentZ`, all deterministic reads, so a `@deterministic` system may ask where the
+ground is. The field reaches a script through `uses`, the way a `NavGraph` does.
+
+## Or as a heightfield, carrying no triangles at all
+
+```ts
+import { heightfieldShape, BODY_STATIC } from '@driftengine/physics';
+
+world.addBody({ type: BODY_STATIC, shape: heightfieldShape(terrain) });
+```
+
+**A `Terrain` _is_ a `Heightfield`** — same names, same meanings — so this type-checks with no
+import in either direction. That is the boundary doing its work rather than being worked around:
+`@driftengine/physics` imports no other engine package, and a shape is not a dependency.
+
+The collider indexes the cell under a body straight from its x and z and holds the heights it was
+handed: no vertex buffer, no index buffer, no tree. At a 129-square field a mesh collider's
+positions and indices alone are **more than five times** the bytes of the heights, before the tree
+over them is counted.
+
+**It is not a second narrow phase.** `meshContact.ts` still owns every contact rule — many
+manifolds rather than one, one-sided triangles, the interior-edge filter that stops a box stumbling
+on a flat seam — and a field only changes _where triangles come from_. The proof is differential:
+both colliders over one field, a box walked across it, and identical normals, counts and
+separations at every pose.
+
+**Which to use.** The mesh path when the collider must be the patch you drew, chords and all — a
+coarse patch collides coarse, and a character then walks on what they can see. The heightfield path
+when the field is the truth and the patches are only how it is drawn, which is the usual case for a
+large world, and the only one of the two whose cost does not grow with the triangles.

package/dist/heightfield.d.ts

@@ -0,0 +1,69 @@
+import type { ReadonlyVec3 } from 'gl-matrix';
+/**
+ * A heightfield, and the two questions everything else asks it.
+ *
+ * **The whole design of this file is one rule: the answer a query gives is the surface that is
+ * drawn.** A heightfield is stored as a lattice of samples and drawn as triangles, and those are
+ * not the same surface — a bilinear patch through four corners and the two triangles that span
+ * them agree only along their shared diagonal and at the corners. Interpolating bilinearly because
+ * it is the obvious thing gives a character that floats over half of every cell and sinks into the
+ * other half, by up to a quarter of the cell's height range, everywhere, for ever. It is a defect
+ * with no symptom a screenshot can show and no test that fails, which is exactly the kind this
+ * repository writes down.
+ *
+ * So `heightAt` reads the *triangle*, and `heightfieldPatch` builds those same triangles, and a
+ * test asserts each vertex against the query.
+ *
+ * **The normal is the other way round on purpose.** A face normal is constant over a triangle and
+ * jumps at every edge, so a field built from them is faceted, and — worse — two patches meeting at
+ * a boundary shade differently along it, which reads as a crack that is not there. `normalAt` is a
+ * central difference over the samples, continuous by construction, and it is what the mesh carries
+ * as its vertex normals. A caller who wants the plane a wheel actually rests on takes three
+ * `heightAt` samples; a caller who wants to orient a character takes this.
+ */
+export interface HeightfieldOptions {
+    /** Samples across x. At least two, since one sample is not a cell. */
+    readonly width: number;
+    /** Samples across z. */
+    readonly depth: number;
+    /** Metres between samples, the same both ways. */
+    readonly spacingM: number;
+    /** `width * depth` heights in metres, row-major with x running fastest. */
+    readonly heights: ArrayLike<number>;
+    /** World position of sample `(0, 0)`. The origin's own y is added to every height. */
+    readonly origin?: ReadonlyVec3;
+}
+export declare class Terrain {
+    readonly width: number;
+    readonly depth: number;
+    readonly spacingM: number;
+    /** World position of sample `(0, 0)`, copied because a caller reuses its vectors. */
+    readonly origin: Float32Array<ArrayBuffer>;
+    /** The samples, copied for the same reason and because this is read every frame. */
+    readonly heights: Float32Array;
+    constructor(options: HeightfieldOptions);
+    /** How far the field reaches along x, metres. One less cell than it has samples. */
+    get extentX(): number;
+    get extentZ(): number;
+    /** One sample, by grid index, clamped to the field rather than wrapping or answering NaN. */
+    sample(ix: number, iz: number): number;
+    /**
+     * The height of the drawn surface at a world position.
+     *
+     * **The triangle and not the bilinear patch**, for the reason at the top of this file. The cell
+     * is split along its `a`-`c` diagonal — from the sample at `(ix, iz)` to the one at
+     * `(ix + 1, iz + 1)` — and `heightfieldPatch` emits exactly that split, so the two cannot
+     * disagree about where the ground is.
+     *
+     * Clamped outside the field. A world has an edge and a query past it should answer the edge
+     * rather than extrapolate a slope into a place that has no samples.
+     */
+    heightAt(x: number, z: number): number;
+    /**
+     * The surface normal at a world position, as a central difference over the samples.
+     *
+     * Continuous across every cell boundary, which is what stops two patches shading differently
+     * along the edge they share — the failure that reads as a crack in geometry that has none.
+     */
+    normalAt(x: number, z: number, out: Float32Array): Float32Array;
+}

package/dist/heightfield.js

@@ -0,0 +1,91 @@
+export class Terrain {
+    width;
+    depth;
+    spacingM;
+    /** World position of sample `(0, 0)`, copied because a caller reuses its vectors. */
+    origin = new Float32Array(3);
+    /** The samples, copied for the same reason and because this is read every frame. */
+    heights;
+    constructor(options) {
+        const { width, depth, spacingM } = options;
+        if (!(width >= 2))
+            throw new Error(`Terrain: width must be at least 2, got ${width}`);
+        if (!(depth >= 2))
+            throw new Error(`Terrain: depth must be at least 2, got ${depth}`);
+        if (!(spacingM > 0))
+            throw new Error(`Terrain: spacing must be above zero, got ${spacingM}`);
+        if (options.heights.length !== width * depth) {
+            throw new Error(`Terrain: ${width} by ${depth} needs ${width * depth} heights, got ${options.heights.length}`);
+        }
+        this.width = Math.round(width);
+        this.depth = Math.round(depth);
+        this.spacingM = spacingM;
+        this.heights = Float32Array.from(options.heights);
+        if (options.origin !== undefined)
+            this.origin.set(options.origin);
+    }
+    /** How far the field reaches along x, metres. One less cell than it has samples. */
+    get extentX() {
+        return (this.width - 1) * this.spacingM;
+    }
+    get extentZ() {
+        return (this.depth - 1) * this.spacingM;
+    }
+    /** One sample, by grid index, clamped to the field rather than wrapping or answering NaN. */
+    sample(ix, iz) {
+        const x = Math.min(this.width - 1, Math.max(0, ix));
+        const z = Math.min(this.depth - 1, Math.max(0, iz));
+        return (this.origin[1] ?? 0) + (this.heights[z * this.width + x] ?? 0);
+    }
+    /**
+     * The height of the drawn surface at a world position.
+     *
+     * **The triangle and not the bilinear patch**, for the reason at the top of this file. The cell
+     * is split along its `a`-`c` diagonal — from the sample at `(ix, iz)` to the one at
+     * `(ix + 1, iz + 1)` — and `heightfieldPatch` emits exactly that split, so the two cannot
+     * disagree about where the ground is.
+     *
+     * Clamped outside the field. A world has an edge and a query past it should answer the edge
+     * rather than extrapolate a slope into a place that has no samples.
+     */
+    heightAt(x, z) {
+        const u = (x - (this.origin[0] ?? 0)) / this.spacingM;
+        const v = (z - (this.origin[2] ?? 0)) / this.spacingM;
+        const clampedU = Math.min(this.width - 1, Math.max(0, u));
+        const clampedV = Math.min(this.depth - 1, Math.max(0, v));
+        /* One short of the last sample, so `ix + 1` is always a sample and the cell is always whole. */
+        const ix = Math.min(this.width - 2, Math.floor(clampedU));
+        const iz = Math.min(this.depth - 2, Math.floor(clampedV));
+        const fu = clampedU - ix;
+        const fv = clampedV - iz;
+        const a = this.sample(ix, iz);
+        const c = this.sample(ix + 1, iz + 1);
+        if (fu >= fv) {
+            /* Below the diagonal: the triangle a, b, c. */
+            const b = this.sample(ix + 1, iz);
+            return a + (b - a) * fu + (c - b) * fv;
+        }
+        /* Above it: the triangle a, c, d. */
+        const d = this.sample(ix, iz + 1);
+        return a + (d - a) * fv + (c - d) * fu;
+    }
+    /**
+     * The surface normal at a world position, as a central difference over the samples.
+     *
+     * Continuous across every cell boundary, which is what stops two patches shading differently
+     * along the edge they share — the failure that reads as a crack in geometry that has none.
+     */
+    normalAt(x, z, out) {
+        const step = this.spacingM;
+        const dx = this.heightAt(x + step, z) - this.heightAt(x - step, z);
+        const dz = this.heightAt(x, z + step) - this.heightAt(x, z - step);
+        /* The gradient of a height field, normalised: (-dh/dx, 1, -dh/dz) over twice the step. */
+        const nx = -dx / (2 * step);
+        const nz = -dz / (2 * step);
+        const length = Math.sqrt(nx * nx + 1 + nz * nz);
+        out[0] = nx / length;
+        out[1] = 1 / length;
+        out[2] = nz / length;
+        return out;
+    }
+}

package/dist/heightfieldPatch.d.ts

@@ -0,0 +1,74 @@
+import type { MeshData } from '@driftengine/drft';
+import type { ReadonlyVec3 } from 'gl-matrix';
+import type { Terrain } from './heightfield.ts';
+import type { TerrainMaterials } from './terrainMaterials.ts';
+/**
+ * One square of a heightfield, as geometry, at a level of detail — and matched to its neighbours.
+ *
+ * **A patch is the unit of detail, and the seam between two of them is the whole problem.** A
+ * heightfield drawn at one resolution is either too coarse underfoot or too fine at the horizon, so
+ * it is drawn in squares and the distant squares skip samples. Where a square that skips none meets
+ * one that skips every other, the fine edge has vertices the coarse edge does not — and those
+ * vertices sit *on the field* while the coarse edge cuts the chord beneath them. The gap between
+ * the two is a crack, and a crack in terrain is a hole through to the sky.
+ *
+ * **Matched rather than hidden.** The usual remedy is a skirt: a vertical curtain dropped from
+ * every patch edge, which fills the hole with something the wrong colour and lit the wrong way, and
+ * costs geometry along every boundary in the world for ever. What this does instead is move the
+ * fine edge's odd vertices onto the coarse edge's own straight segment, so the two edges are the
+ * same polyline and there is nothing to fill. It costs one interpolation per boundary vertex, at
+ * build time, and no geometry at all.
+ *
+ * **The cost of matching, stated because it is real**: along a matched edge the drawn surface is
+ * the coarse chord rather than the field, so `Terrain.heightAt` and the picture differ there by up
+ * to the sag of one coarse cell. That is the same error the coarse patch itself carries over its
+ * whole area, arriving one cell early — which is why it is the right trade and why it is written
+ * down rather than left to be discovered.
+ */
+export interface HeightfieldPatchOptions {
+    /** Grid index of the patch's first sample, along x. */
+    readonly x: number;
+    /** Grid index of the patch's first sample, along z. */
+    readonly z: number;
+    /** How many field cells the patch spans. */
+    readonly cells: number;
+    /**
+     * How many field cells one drawn cell spans. 1 is full resolution.
+     *
+     * Must divide `cells`, since a patch that does not come out whole would leave a strip of the
+     * field undrawn — a crack that no neighbour can match because nothing is there to match.
+     */
+    readonly step?: number;
+    /**
+     * The step each neighbouring patch is drawn at, where it is coarser than this one.
+     *
+     * Only the coarser side needs naming: the finer patch is the one that moves. A neighbour at the
+     * same step or a finer one changes nothing, so a caller may pass what it knows and leave the
+     * rest out.
+     */
+    readonly neighbours?: {
+        readonly minusX?: number;
+        readonly plusX?: number;
+        readonly minusZ?: number;
+        readonly plusZ?: number;
+    };
+    /**
+     * One colour for the whole patch. Ignored where `materials` is given.
+     *
+     * Two ways to say the same thing would be a mistake, and this is not one: a patch with a single
+     * colour is what a caller writes before they have a weight map, and a map is what they write once
+     * they have several materials. The second wins where both are present, said here so it is not
+     * discovered.
+     */
+    readonly color?: ReadonlyVec3;
+    readonly emissive?: number;
+    /**
+     * Several materials blended across the *field*, rather than one colour for this patch.
+     *
+     * **Read in the field's own coordinates and never the patch's**, which is what makes two patches
+     * agree along the edge they share. Shading from a patch-local coordinate would restart the blend
+     * at every boundary and draw a grid of squares over the world.
+     */
+    readonly materials?: TerrainMaterials;
+}
+export declare function heightfieldPatch(terrain: Terrain, options: HeightfieldPatchOptions): MeshData;