@hello-terrain/three 0.0.0-alpha.1

package/README.md

@@ -0,0 +1,42 @@
+# @hello-terrain/three
+Realtime web terrain engine, for vast virtual worlds. Built for [three.js](https://threejs.org/).
+## Features
+
+- Performant variable LOD system for huge (earth-scale!) open worlds
+- Elevation manipulation, terrain holes, texture painting, overlays, colors, and wetness
+- TSL-based elevation and texture assignment nodes
+- Composable compute stage plugins
+
+## Getting Started
+
+1. Read the [Introduction](http://hello-terrain.kenny.wtf/docs) to understand the architecture and see how it's used.
+
+2. Read the [Installation](http://hello-terrain.kenny.wtf/docs/installation) instructions.
+
+3. Review the [Examples](http://hello-terrain.kenny.wtf/examples) to get an idea of how to do things.
+
+4. For support, join the [Discord server](https://discord.gg/HgTd2B828n).
+
+## Project Architecture
+This library uses [unbuild](https://github.com/unjs/unbuild) for building.
+- `src/index.ts` is the main entry point for your library exports
+- Add your library code in the `src` folder
+- `tests/` contains your test files
+
+
+## Libraries
+The following libraries are used - checkout the linked docs to learn more
+- [unbuild](https://github.com/unjs/unbuild) - Unified JavaScript build system
+
+
+## Tools
+- [Vitest](https://vitest.dev/) - Fast unit test framework powered by Vite
+- [Oxlint](https://oxc.rs/docs/guide/usage/linter) - A fast linter for JavaScript and TypeScript
+- [Oxfmt](https://oxc.rs/docs/guide/usage/formatter) - Fast Prettier-compatible code formatter
+
+
+## Development Commands
+- `pnpm install` to install the dependencies
+- `pnpm run build` to build the library into the `dist` folder
+- `pnpm run test` to run the tests
+- `pnpm run release` to build and publish to npm

package/dist/index.cjs

@@ -0,0 +1,240 @@
+'use strict';
+
+const three = require('three');
+const tsl = require('three/tsl');
+
+class TerrainGeometry extends three.BufferGeometry {
+  constructor(innerSegments = 14, extendUV = false) {
+    super();
+    if (innerSegments < 1 || !Number.isFinite(innerSegments) || !Number.isInteger(innerSegments)) {
+      throw new Error(
+        `Invalid innerSegments: ${innerSegments}. Must be a positive integer.`
+      );
+    }
+    try {
+      this.setIndex(this.generateIndices(innerSegments));
+      this.setAttribute(
+        "position",
+        new three.BufferAttribute(
+          new Float32Array(this.generatePositions(innerSegments)),
+          3
+        )
+      );
+      this.setAttribute(
+        "normal",
+        new three.BufferAttribute(
+          new Float32Array(this.generateNormals(innerSegments)),
+          3
+        )
+      );
+      this.setAttribute(
+        "uv",
+        new three.BufferAttribute(
+          new Float32Array(
+            extendUV ? this.generateUvsExtended(innerSegments) : this.generateUvsOnlyInner(innerSegments)
+          ),
+          2
+        )
+      );
+    } catch (error) {
+      console.error("Error creating TerrainGeometry:", error);
+      throw error;
+    }
+  }
+  /**
+   * Generate indices for terrain geometry with proper skirt corner handling.
+   * The key improvement is in how corner triangles are subdivided.
+   */
+  /**
+   * Generate indices for terrain geometry with proper skirt corner handling.
+   *
+   * The mesh layout is a regular grid (with duplicated outermost ring for skirt):
+   *
+   * SKIRT RING (rotational symmetry for proper corners):
+   *  o---o---o---o---o
+   *  | \ | / | \ | / |
+   *  o---o---o---o---o
+   *  | / |       | \ |
+   *  o---o       o---o
+   *  | \ |       | / |
+   *  o---o---o---o---o
+   *  | / | \ | / | \ |
+   *  o---o---o---o---o
+   *
+   * INNER GRID (consistent diagonal, no rotational symmetry):
+   *        o---o---o
+   *        | \ | \ |
+   *        o---o---o
+   *        | \ | \ |
+   *        o---o---o
+   *
+   * Where o = vertex
+   * Each square cell is split into 2 triangles.
+   * - Skirt cells (outer ring): diagonal flip based on quadrant for corner correctness
+   * - Inner cells: consistent diagonal direction (all triangles "point" the same way)
+   *
+   * Vertex layout (for innerSegments = 2):
+   *
+   *    0----1----2----3----4
+   *    |    |    |    |    |
+   *    5----6----7----8----9
+   *    |    |    |    |    |
+   *   10---11---12---13---14
+   *    |    |    |    |    |
+   *   15---16---17---18---19
+   *    |    |    |    |    |
+   *   20---21---22---23---24
+   *
+   * For each cell:
+   *   a = top-left,
+   *   b = top-right,
+   *   c = bottom-left,
+   *   d = bottom-right (all as flat array indices)
+   *
+   * Diagonal a-d:
+   *   triangle 1: a, d, b
+   *   triangle 2: a, c, d
+   * Diagonal b-c:
+   *   triangle 1: a, c, b
+   *   triangle 2: b, c, d
+   */
+  generateIndices(innerSegments) {
+    const innerEdgeVertexCount = innerSegments + 1;
+    const edgeVertexCountWithSkirt = innerEdgeVertexCount + 2;
+    const indices = [];
+    const cellsPerEdge = edgeVertexCountWithSkirt - 1;
+    const mid = Math.floor(cellsPerEdge / 2);
+    for (let y = 0; y < cellsPerEdge; y++) {
+      for (let x = 0; x < cellsPerEdge; x++) {
+        const a = y * edgeVertexCountWithSkirt + x;
+        const b = a + 1;
+        const c = a + edgeVertexCountWithSkirt;
+        const d = c + 1;
+        const isSkirtCell = x === 0 || x === cellsPerEdge - 1 || y === 0 || y === cellsPerEdge - 1;
+        let useDefaultDiagonal;
+        if (isSkirtCell) {
+          const leftHalf = x < mid;
+          const topHalf = y < mid;
+          useDefaultDiagonal = leftHalf && topHalf || !leftHalf && !topHalf;
+        } else {
+          useDefaultDiagonal = true;
+        }
+        if (useDefaultDiagonal) {
+          indices.push(a, d, b);
+          indices.push(a, c, d);
+        } else {
+          indices.push(a, c, b);
+          indices.push(b, c, d);
+        }
+      }
+    }
+    return indices;
+  }
+  /**
+   * Generate vertex positions for the terrain with skirts.
+   * Positions are normalized to [-0.5, 0.5] range.
+   */
+  generatePositions(innerSegments) {
+    const edgeVertexCountWithSkirt = innerSegments + 1 + 2;
+    const positions = [];
+    for (let iy = 0; iy < edgeVertexCountWithSkirt; iy++) {
+      const v = Math.min(Math.max((iy - 1) / innerSegments, 0), 1);
+      const z = v - 0.5;
+      for (let ix = 0; ix < edgeVertexCountWithSkirt; ix++) {
+        const u = Math.min(Math.max((ix - 1) / innerSegments, 0), 1);
+        const x = u - 0.5;
+        positions.push(x, 0, z);
+      }
+    }
+    return positions;
+  }
+  /**
+   * Generate UV coordinates for the inner grid only (skirt duplicates clamped to border).
+   * UVs are normalized to [0, 1] range with flipped V.
+   */
+  generateUvsOnlyInner(innerSegments) {
+    const edgeVertexCountWithSkirt = innerSegments + 1 + 2;
+    const uvs = [];
+    for (let iy = 0; iy < edgeVertexCountWithSkirt; iy++) {
+      const v = Math.min(Math.max((iy - 1) / innerSegments, 0), 1);
+      for (let ix = 0; ix < edgeVertexCountWithSkirt; ix++) {
+        const u = Math.min(Math.max((ix - 1) / innerSegments, 0), 1);
+        uvs.push(u, 1 - v);
+      }
+    }
+    return uvs;
+  }
+  /**
+   * Generate UVs that extend 1 extra unit outward to the skirt ring.
+   * Map the entire geometry (including skirts) into [0,1] so side faces
+   * receive proper UVs without relying on texture wrapping. V is flipped.
+   */
+  generateUvsExtended(innerSegments) {
+    const edgeVertexCountWithSkirt = innerSegments + 1 + 2;
+    const uvs = [];
+    const denom = edgeVertexCountWithSkirt - 1;
+    for (let iy = 0; iy < edgeVertexCountWithSkirt; iy++) {
+      const v = iy / denom;
+      for (let ix = 0; ix < edgeVertexCountWithSkirt; ix++) {
+        const u = ix / denom;
+        uvs.push(u, 1 - v);
+      }
+    }
+    return uvs;
+  }
+  /**
+   * Generate vertex normals.
+   */
+  generateNormals(innerSegments) {
+    const edgeVertexCountWithSkirt = innerSegments + 1 + 2;
+    const last = edgeVertexCountWithSkirt - 1;
+    const normals = [];
+    for (let iy = 0; iy < edgeVertexCountWithSkirt; iy++) {
+      for (let ix = 0; ix < edgeVertexCountWithSkirt; ix++) {
+        const onEdgeX = ix === 0 || ix === last;
+        const onEdgeY = iy === 0 || iy === last;
+        if (onEdgeX || onEdgeY) {
+          let nx = 0;
+          let nz = 0;
+          if (ix === 0) nx -= 1;
+          if (ix === last) nx += 1;
+          if (iy === 0) nz -= 1;
+          if (iy === last) nz += 1;
+          const len = Math.hypot(nx, nz);
+          if (len > 0) {
+            normals.push(nx / len, 0, nz / len);
+          } else {
+            normals.push(0, 1, 0);
+          }
+        } else {
+          normals.push(0, 1, 0);
+        }
+      }
+    }
+    return normals;
+  }
+}
+
+const isSkirtVertex = tsl.Fn(([segments]) => {
+  const segmentsNode = typeof segments === "number" ? tsl.int(segments) : segments;
+  const vIndex = tsl.int(tsl.vertexIndex);
+  const segmentEdges = tsl.int(segmentsNode.add(3));
+  const vx = vIndex.mod(segmentEdges);
+  const vy = vIndex.div(segmentEdges);
+  const last = segmentEdges.sub(tsl.int(1));
+  return vx.equal(tsl.int(0)).or(vx.equal(last)).or(vy.equal(tsl.int(0))).or(vy.equal(last));
+});
+const isSkirtUV = tsl.Fn(([segments]) => {
+  const segmentsNode = typeof segments === "number" ? tsl.int(segments) : segments;
+  const ux = tsl.uv().x;
+  const uy = tsl.uv().y;
+  const segmentCount = segmentsNode.add(2);
+  const segmentStep = tsl.float(1).div(segmentCount);
+  const innerX = ux.greaterThan(segmentStep).and(ux.lessThan(segmentStep.oneMinus()));
+  const innerY = uy.greaterThan(segmentStep).and(uy.lessThan(segmentStep.oneMinus()));
+  return innerX.and(innerY).not();
+});
+
+exports.TerrainGeometry = TerrainGeometry;
+exports.isSkirtUV = isSkirtUV;
+exports.isSkirtVertex = isSkirtVertex;

package/dist/index.d.cts

@@ -0,0 +1,116 @@
+import { BufferGeometry } from 'three';
+import * as three_src_nodes_TSL_js from 'three/src/nodes/TSL.js';
+import { Node } from 'three/webgpu';
+
+/**
+ * Custom geometry for terrain tiles with properly handled skirts.
+ * This geometry ensures that corner triangles are subdivided correctly.
+ */
+declare class TerrainGeometry extends BufferGeometry {
+    constructor(innerSegments?: number, extendUV?: boolean);
+    /**
+     * Generate indices for terrain geometry with proper skirt corner handling.
+     * The key improvement is in how corner triangles are subdivided.
+     */
+    /**
+     * Generate indices for terrain geometry with proper skirt corner handling.
+     *
+     * The mesh layout is a regular grid (with duplicated outermost ring for skirt):
+     *
+     * SKIRT RING (rotational symmetry for proper corners):
+     *  o---o---o---o---o
+     *  | \ | / | \ | / |
+     *  o---o---o---o---o
+     *  | / |       | \ |
+     *  o---o       o---o
+     *  | \ |       | / |
+     *  o---o---o---o---o
+     *  | / | \ | / | \ |
+     *  o---o---o---o---o
+     *
+     * INNER GRID (consistent diagonal, no rotational symmetry):
+     *        o---o---o
+     *        | \ | \ |
+     *        o---o---o
+     *        | \ | \ |
+     *        o---o---o
+     *
+     * Where o = vertex
+     * Each square cell is split into 2 triangles.
+     * - Skirt cells (outer ring): diagonal flip based on quadrant for corner correctness
+     * - Inner cells: consistent diagonal direction (all triangles "point" the same way)
+     *
+     * Vertex layout (for innerSegments = 2):
+     *
+     *    0----1----2----3----4
+     *    |    |    |    |    |
+     *    5----6----7----8----9
+     *    |    |    |    |    |
+     *   10---11---12---13---14
+     *    |    |    |    |    |
+     *   15---16---17---18---19
+     *    |    |    |    |    |
+     *   20---21---22---23---24
+     *
+     * For each cell:
+     *   a = top-left,
+     *   b = top-right,
+     *   c = bottom-left,
+     *   d = bottom-right (all as flat array indices)
+     *
+     * Diagonal a-d:
+     *   triangle 1: a, d, b
+     *   triangle 2: a, c, d
+     * Diagonal b-c:
+     *   triangle 1: a, c, b
+     *   triangle 2: b, c, d
+     */
+    private generateIndices;
+    /**
+     * Generate vertex positions for the terrain with skirts.
+     * Positions are normalized to [-0.5, 0.5] range.
+     */
+    private generatePositions;
+    /**
+     * Generate UV coordinates for the inner grid only (skirt duplicates clamped to border).
+     * UVs are normalized to [0, 1] range with flipped V.
+     */
+    private generateUvsOnlyInner;
+    /**
+     * Generate UVs that extend 1 extra unit outward to the skirt ring.
+     * Map the entire geometry (including skirts) into [0,1] so side faces
+     * receive proper UVs without relying on texture wrapping. V is flipped.
+     */
+    private generateUvsExtended;
+    /**
+     * Generate vertex normals.
+     */
+    private generateNormals;
+}
+
+/**
+ * Returns a node that is true for skirt vertices in the vertex stage.
+ *
+ * @remarks
+ * Only valid in the vertex shader. A vertex belongs to the skirt if it is on
+ * the outermost ring of the tile grid (first/last column or row). The grid
+ * resolution is derived from `segments`.
+ *
+ * @param segments - The number of inner segments in the terrain grid.
+ * @returns A node resolving to a boolean indicating a skirt vertex.
+ */
+declare const isSkirtVertex: three_src_nodes_TSL_js.ShaderNodeFn<[segments: number | Node]>;
+/**
+ * Returns a node that is true for skirt UVs.
+ *
+ * @remarks
+ * Uses interpolated UVs and the grid size
+ * from `segments` to mark fragments outside the inner range
+ * `(step, 1 - step)` on either axis as skirt, where `step = 1 / (segments + 2)`.
+ *
+ * @param segments - The number of inner segments in the terrain grid.
+ * @returns A node resolving to a boolean indicating a skirt fragment.
+ */
+declare const isSkirtUV: three_src_nodes_TSL_js.ShaderNodeFn<[segments: number | Node]>;
+
+export { TerrainGeometry, isSkirtUV, isSkirtVertex };

package/dist/index.d.mts

@@ -0,0 +1,116 @@
+import { BufferGeometry } from 'three';
+import * as three_src_nodes_TSL_js from 'three/src/nodes/TSL.js';
+import { Node } from 'three/webgpu';
+
+/**
+ * Custom geometry for terrain tiles with properly handled skirts.
+ * This geometry ensures that corner triangles are subdivided correctly.
+ */
+declare class TerrainGeometry extends BufferGeometry {
+    constructor(innerSegments?: number, extendUV?: boolean);
+    /**
+     * Generate indices for terrain geometry with proper skirt corner handling.
+     * The key improvement is in how corner triangles are subdivided.
+     */
+    /**
+     * Generate indices for terrain geometry with proper skirt corner handling.
+     *
+     * The mesh layout is a regular grid (with duplicated outermost ring for skirt):
+     *
+     * SKIRT RING (rotational symmetry for proper corners):
+     *  o---o---o---o---o
+     *  | \ | / | \ | / |
+     *  o---o---o---o---o
+     *  | / |       | \ |
+     *  o---o       o---o
+     *  | \ |       | / |
+     *  o---o---o---o---o
+     *  | / | \ | / | \ |
+     *  o---o---o---o---o
+     *
+     * INNER GRID (consistent diagonal, no rotational symmetry):
+     *        o---o---o
+     *        | \ | \ |
+     *        o---o---o
+     *        | \ | \ |
+     *        o---o---o
+     *
+     * Where o = vertex
+     * Each square cell is split into 2 triangles.
+     * - Skirt cells (outer ring): diagonal flip based on quadrant for corner correctness
+     * - Inner cells: consistent diagonal direction (all triangles "point" the same way)
+     *
+     * Vertex layout (for innerSegments = 2):
+     *
+     *    0----1----2----3----4
+     *    |    |    |    |    |
+     *    5----6----7----8----9
+     *    |    |    |    |    |
+     *   10---11---12---13---14
+     *    |    |    |    |    |
+     *   15---16---17---18---19
+     *    |    |    |    |    |
+     *   20---21---22---23---24
+     *
+     * For each cell:
+     *   a = top-left,
+     *   b = top-right,
+     *   c = bottom-left,
+     *   d = bottom-right (all as flat array indices)
+     *
+     * Diagonal a-d:
+     *   triangle 1: a, d, b
+     *   triangle 2: a, c, d
+     * Diagonal b-c:
+     *   triangle 1: a, c, b
+     *   triangle 2: b, c, d
+     */
+    private generateIndices;
+    /**
+     * Generate vertex positions for the terrain with skirts.
+     * Positions are normalized to [-0.5, 0.5] range.
+     */
+    private generatePositions;
+    /**
+     * Generate UV coordinates for the inner grid only (skirt duplicates clamped to border).
+     * UVs are normalized to [0, 1] range with flipped V.
+     */
+    private generateUvsOnlyInner;
+    /**
+     * Generate UVs that extend 1 extra unit outward to the skirt ring.
+     * Map the entire geometry (including skirts) into [0,1] so side faces
+     * receive proper UVs without relying on texture wrapping. V is flipped.
+     */
+    private generateUvsExtended;
+    /**
+     * Generate vertex normals.
+     */
+    private generateNormals;
+}
+
+/**
+ * Returns a node that is true for skirt vertices in the vertex stage.
+ *
+ * @remarks
+ * Only valid in the vertex shader. A vertex belongs to the skirt if it is on
+ * the outermost ring of the tile grid (first/last column or row). The grid
+ * resolution is derived from `segments`.
+ *
+ * @param segments - The number of inner segments in the terrain grid.
+ * @returns A node resolving to a boolean indicating a skirt vertex.
+ */
+declare const isSkirtVertex: three_src_nodes_TSL_js.ShaderNodeFn<[segments: number | Node]>;
+/**
+ * Returns a node that is true for skirt UVs.
+ *
+ * @remarks
+ * Uses interpolated UVs and the grid size
+ * from `segments` to mark fragments outside the inner range
+ * `(step, 1 - step)` on either axis as skirt, where `step = 1 / (segments + 2)`.
+ *
+ * @param segments - The number of inner segments in the terrain grid.
+ * @returns A node resolving to a boolean indicating a skirt fragment.
+ */
+declare const isSkirtUV: three_src_nodes_TSL_js.ShaderNodeFn<[segments: number | Node]>;
+
+export { TerrainGeometry, isSkirtUV, isSkirtVertex };

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+import { BufferGeometry } from 'three';
+import * as three_src_nodes_TSL_js from 'three/src/nodes/TSL.js';
+import { Node } from 'three/webgpu';
+
+/**
+ * Custom geometry for terrain tiles with properly handled skirts.
+ * This geometry ensures that corner triangles are subdivided correctly.
+ */
+declare class TerrainGeometry extends BufferGeometry {
+    constructor(innerSegments?: number, extendUV?: boolean);
+    /**
+     * Generate indices for terrain geometry with proper skirt corner handling.
+     * The key improvement is in how corner triangles are subdivided.
+     */
+    /**
+     * Generate indices for terrain geometry with proper skirt corner handling.
+     *
+     * The mesh layout is a regular grid (with duplicated outermost ring for skirt):
+     *
+     * SKIRT RING (rotational symmetry for proper corners):
+     *  o---o---o---o---o
+     *  | \ | / | \ | / |
+     *  o---o---o---o---o
+     *  | / |       | \ |
+     *  o---o       o---o
+     *  | \ |       | / |
+     *  o---o---o---o---o
+     *  | / | \ | / | \ |
+     *  o---o---o---o---o
+     *
+     * INNER GRID (consistent diagonal, no rotational symmetry):
+     *        o---o---o
+     *        | \ | \ |
+     *        o---o---o
+     *        | \ | \ |
+     *        o---o---o
+     *
+     * Where o = vertex
+     * Each square cell is split into 2 triangles.
+     * - Skirt cells (outer ring): diagonal flip based on quadrant for corner correctness
+     * - Inner cells: consistent diagonal direction (all triangles "point" the same way)
+     *
+     * Vertex layout (for innerSegments = 2):
+     *
+     *    0----1----2----3----4
+     *    |    |    |    |    |
+     *    5----6----7----8----9
+     *    |    |    |    |    |
+     *   10---11---12---13---14
+     *    |    |    |    |    |
+     *   15---16---17---18---19
+     *    |    |    |    |    |
+     *   20---21---22---23---24
+     *
+     * For each cell:
+     *   a = top-left,
+     *   b = top-right,
+     *   c = bottom-left,
+     *   d = bottom-right (all as flat array indices)
+     *
+     * Diagonal a-d:
+     *   triangle 1: a, d, b
+     *   triangle 2: a, c, d
+     * Diagonal b-c:
+     *   triangle 1: a, c, b
+     *   triangle 2: b, c, d
+     */
+    private generateIndices;
+    /**
+     * Generate vertex positions for the terrain with skirts.
+     * Positions are normalized to [-0.5, 0.5] range.
+     */
+    private generatePositions;
+    /**
+     * Generate UV coordinates for the inner grid only (skirt duplicates clamped to border).
+     * UVs are normalized to [0, 1] range with flipped V.
+     */
+    private generateUvsOnlyInner;
+    /**
+     * Generate UVs that extend 1 extra unit outward to the skirt ring.
+     * Map the entire geometry (including skirts) into [0,1] so side faces
+     * receive proper UVs without relying on texture wrapping. V is flipped.
+     */
+    private generateUvsExtended;
+    /**
+     * Generate vertex normals.
+     */
+    private generateNormals;
+}
+
+/**
+ * Returns a node that is true for skirt vertices in the vertex stage.
+ *
+ * @remarks
+ * Only valid in the vertex shader. A vertex belongs to the skirt if it is on
+ * the outermost ring of the tile grid (first/last column or row). The grid
+ * resolution is derived from `segments`.
+ *
+ * @param segments - The number of inner segments in the terrain grid.
+ * @returns A node resolving to a boolean indicating a skirt vertex.
+ */
+declare const isSkirtVertex: three_src_nodes_TSL_js.ShaderNodeFn<[segments: number | Node]>;
+/**
+ * Returns a node that is true for skirt UVs.
+ *
+ * @remarks
+ * Uses interpolated UVs and the grid size
+ * from `segments` to mark fragments outside the inner range
+ * `(step, 1 - step)` on either axis as skirt, where `step = 1 / (segments + 2)`.
+ *
+ * @param segments - The number of inner segments in the terrain grid.
+ * @returns A node resolving to a boolean indicating a skirt fragment.
+ */
+declare const isSkirtUV: three_src_nodes_TSL_js.ShaderNodeFn<[segments: number | Node]>;
+
+export { TerrainGeometry, isSkirtUV, isSkirtVertex };

package/dist/index.mjs

@@ -0,0 +1,236 @@
+import { BufferGeometry, BufferAttribute } from 'three';
+import { Fn, int, vertexIndex, uv, float } from 'three/tsl';
+
+class TerrainGeometry extends BufferGeometry {
+  constructor(innerSegments = 14, extendUV = false) {
+    super();
+    if (innerSegments < 1 || !Number.isFinite(innerSegments) || !Number.isInteger(innerSegments)) {
+      throw new Error(
+        `Invalid innerSegments: ${innerSegments}. Must be a positive integer.`
+      );
+    }
+    try {
+      this.setIndex(this.generateIndices(innerSegments));
+      this.setAttribute(
+        "position",
+        new BufferAttribute(
+          new Float32Array(this.generatePositions(innerSegments)),
+          3
+        )
+      );
+      this.setAttribute(
+        "normal",
+        new BufferAttribute(
+          new Float32Array(this.generateNormals(innerSegments)),
+          3
+        )
+      );
+      this.setAttribute(
+        "uv",
+        new BufferAttribute(
+          new Float32Array(
+            extendUV ? this.generateUvsExtended(innerSegments) : this.generateUvsOnlyInner(innerSegments)
+          ),
+          2
+        )
+      );
+    } catch (error) {
+      console.error("Error creating TerrainGeometry:", error);
+      throw error;
+    }
+  }
+  /**
+   * Generate indices for terrain geometry with proper skirt corner handling.
+   * The key improvement is in how corner triangles are subdivided.
+   */
+  /**
+   * Generate indices for terrain geometry with proper skirt corner handling.
+   *
+   * The mesh layout is a regular grid (with duplicated outermost ring for skirt):
+   *
+   * SKIRT RING (rotational symmetry for proper corners):
+   *  o---o---o---o---o
+   *  | \ | / | \ | / |
+   *  o---o---o---o---o
+   *  | / |       | \ |
+   *  o---o       o---o
+   *  | \ |       | / |
+   *  o---o---o---o---o
+   *  | / | \ | / | \ |
+   *  o---o---o---o---o
+   *
+   * INNER GRID (consistent diagonal, no rotational symmetry):
+   *        o---o---o
+   *        | \ | \ |
+   *        o---o---o
+   *        | \ | \ |
+   *        o---o---o
+   *
+   * Where o = vertex
+   * Each square cell is split into 2 triangles.
+   * - Skirt cells (outer ring): diagonal flip based on quadrant for corner correctness
+   * - Inner cells: consistent diagonal direction (all triangles "point" the same way)
+   *
+   * Vertex layout (for innerSegments = 2):
+   *
+   *    0----1----2----3----4
+   *    |    |    |    |    |
+   *    5----6----7----8----9
+   *    |    |    |    |    |
+   *   10---11---12---13---14
+   *    |    |    |    |    |
+   *   15---16---17---18---19
+   *    |    |    |    |    |
+   *   20---21---22---23---24
+   *
+   * For each cell:
+   *   a = top-left,
+   *   b = top-right,
+   *   c = bottom-left,
+   *   d = bottom-right (all as flat array indices)
+   *
+   * Diagonal a-d:
+   *   triangle 1: a, d, b
+   *   triangle 2: a, c, d
+   * Diagonal b-c:
+   *   triangle 1: a, c, b
+   *   triangle 2: b, c, d
+   */
+  generateIndices(innerSegments) {
+    const innerEdgeVertexCount = innerSegments + 1;
+    const edgeVertexCountWithSkirt = innerEdgeVertexCount + 2;
+    const indices = [];
+    const cellsPerEdge = edgeVertexCountWithSkirt - 1;
+    const mid = Math.floor(cellsPerEdge / 2);
+    for (let y = 0; y < cellsPerEdge; y++) {
+      for (let x = 0; x < cellsPerEdge; x++) {
+        const a = y * edgeVertexCountWithSkirt + x;
+        const b = a + 1;
+        const c = a + edgeVertexCountWithSkirt;
+        const d = c + 1;
+        const isSkirtCell = x === 0 || x === cellsPerEdge - 1 || y === 0 || y === cellsPerEdge - 1;
+        let useDefaultDiagonal;
+        if (isSkirtCell) {
+          const leftHalf = x < mid;
+          const topHalf = y < mid;
+          useDefaultDiagonal = leftHalf && topHalf || !leftHalf && !topHalf;
+        } else {
+          useDefaultDiagonal = true;
+        }
+        if (useDefaultDiagonal) {
+          indices.push(a, d, b);
+          indices.push(a, c, d);
+        } else {
+          indices.push(a, c, b);
+          indices.push(b, c, d);
+        }
+      }
+    }
+    return indices;
+  }
+  /**
+   * Generate vertex positions for the terrain with skirts.
+   * Positions are normalized to [-0.5, 0.5] range.
+   */
+  generatePositions(innerSegments) {
+    const edgeVertexCountWithSkirt = innerSegments + 1 + 2;
+    const positions = [];
+    for (let iy = 0; iy < edgeVertexCountWithSkirt; iy++) {
+      const v = Math.min(Math.max((iy - 1) / innerSegments, 0), 1);
+      const z = v - 0.5;
+      for (let ix = 0; ix < edgeVertexCountWithSkirt; ix++) {
+        const u = Math.min(Math.max((ix - 1) / innerSegments, 0), 1);
+        const x = u - 0.5;
+        positions.push(x, 0, z);
+      }
+    }
+    return positions;
+  }
+  /**
+   * Generate UV coordinates for the inner grid only (skirt duplicates clamped to border).
+   * UVs are normalized to [0, 1] range with flipped V.
+   */
+  generateUvsOnlyInner(innerSegments) {
+    const edgeVertexCountWithSkirt = innerSegments + 1 + 2;
+    const uvs = [];
+    for (let iy = 0; iy < edgeVertexCountWithSkirt; iy++) {
+      const v = Math.min(Math.max((iy - 1) / innerSegments, 0), 1);
+      for (let ix = 0; ix < edgeVertexCountWithSkirt; ix++) {
+        const u = Math.min(Math.max((ix - 1) / innerSegments, 0), 1);
+        uvs.push(u, 1 - v);
+      }
+    }
+    return uvs;
+  }
+  /**
+   * Generate UVs that extend 1 extra unit outward to the skirt ring.
+   * Map the entire geometry (including skirts) into [0,1] so side faces
+   * receive proper UVs without relying on texture wrapping. V is flipped.
+   */
+  generateUvsExtended(innerSegments) {
+    const edgeVertexCountWithSkirt = innerSegments + 1 + 2;
+    const uvs = [];
+    const denom = edgeVertexCountWithSkirt - 1;
+    for (let iy = 0; iy < edgeVertexCountWithSkirt; iy++) {
+      const v = iy / denom;
+      for (let ix = 0; ix < edgeVertexCountWithSkirt; ix++) {
+        const u = ix / denom;
+        uvs.push(u, 1 - v);
+      }
+    }
+    return uvs;
+  }
+  /**
+   * Generate vertex normals.
+   */
+  generateNormals(innerSegments) {
+    const edgeVertexCountWithSkirt = innerSegments + 1 + 2;
+    const last = edgeVertexCountWithSkirt - 1;
+    const normals = [];
+    for (let iy = 0; iy < edgeVertexCountWithSkirt; iy++) {
+      for (let ix = 0; ix < edgeVertexCountWithSkirt; ix++) {
+        const onEdgeX = ix === 0 || ix === last;
+        const onEdgeY = iy === 0 || iy === last;
+        if (onEdgeX || onEdgeY) {
+          let nx = 0;
+          let nz = 0;
+          if (ix === 0) nx -= 1;
+          if (ix === last) nx += 1;
+          if (iy === 0) nz -= 1;
+          if (iy === last) nz += 1;
+          const len = Math.hypot(nx, nz);
+          if (len > 0) {
+            normals.push(nx / len, 0, nz / len);
+          } else {
+            normals.push(0, 1, 0);
+          }
+        } else {
+          normals.push(0, 1, 0);
+        }
+      }
+    }
+    return normals;
+  }
+}
+
+const isSkirtVertex = Fn(([segments]) => {
+  const segmentsNode = typeof segments === "number" ? int(segments) : segments;
+  const vIndex = int(vertexIndex);
+  const segmentEdges = int(segmentsNode.add(3));
+  const vx = vIndex.mod(segmentEdges);
+  const vy = vIndex.div(segmentEdges);
+  const last = segmentEdges.sub(int(1));
+  return vx.equal(int(0)).or(vx.equal(last)).or(vy.equal(int(0))).or(vy.equal(last));
+});
+const isSkirtUV = Fn(([segments]) => {
+  const segmentsNode = typeof segments === "number" ? int(segments) : segments;
+  const ux = uv().x;
+  const uy = uv().y;
+  const segmentCount = segmentsNode.add(2);
+  const segmentStep = float(1).div(segmentCount);
+  const innerX = ux.greaterThan(segmentStep).and(ux.lessThan(segmentStep.oneMinus()));
+  const innerY = uy.greaterThan(segmentStep).and(uy.lessThan(segmentStep.oneMinus()));
+  return innerX.and(innerY).not();
+});
+
+export { TerrainGeometry, isSkirtUV, isSkirtVertex };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@hello-terrain/three",
+  "description": "High performance terrain system for three.js",
+  "version": "0.0.0-alpha.1",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "three": ">=0.182.0"
+  },
+  "devDependencies": {
+    "unbuild": "^3.5.0",
+    "vitest": "^4.0.16",
+    "@types/three": ">=0.182.0",
+    "@config/oxfmt": "0.1.0",
+    "@config/oxlint": "0.1.0",
+    "@config/typescript": "0.1.0"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "release": "pnpm run build && pnpm publish --access=public",
+    "test": "vitest",
+    "lint": "oxlint -c node_modules/@config/oxlint/base.json",
+    "format": "oxfmt -c node_modules/@config/oxfmt/base.json --write ."
+  }
+}