@web-engine-dev/terrain

Large-scale terrain rendering using Continuous Distance-Dependent Level of Detail (CDLOD) with GPU-based heightmap sampling. Supports multi-layer material splatting, vegetation instancing, and seamless LOD transitions.

Layer 6 · Visual Output

Features

• CDLOD Algorithm: Continuous LOD with no popping — smooth geomorphing transitions
• GPU Heightmap Sampling: Vertex displacement in the vertex shader for zero CPU overhead
• Quadtree Structure: Hierarchical terrain patches with frustum and horizon culling
• Material Splatting: Multi-layer terrain materials with blend maps (grass, rock, sand, snow)
• Normal Map Generation: Computed from heightmap for per-pixel terrain lighting
• Vegetation Instancing: GPU-instanced grass, trees, and foliage with distance-based density
• Dynamic LOD Selection: Camera distance drives patch detail level
• Triplanar Mapping: Prevents texture stretching on steep slopes
• Hole Punching: Per-cell terrain holes for caves and tunnels
• Streaming: On-demand tile loading for unbounded world sizes

Installation

npm install @web-engine-dev/terrain
# or
pnpm add @web-engine-dev/terrain

Quick Start

import { Terrain, TerrainMaterial } from '@web-engine-dev/terrain';

// Create terrain from heightmap
const terrain = new Terrain({
  heightmap: heightmapTexture, // R16 or R32F heightmap
  size: { width: 1024, depth: 1024 },
  height: 100,
  patchResolution: 33, // Vertices per patch edge
  lodLevels: 6,
});

// Add material layers
terrain.addLayer({
  material: grassMaterial,
  splatChannel: 'r',
  tiling: 32,
  triplanar: false,
});

terrain.addLayer({
  material: rockMaterial,
  splatChannel: 'g',
  tiling: 16,
  triplanar: true, // Prevents stretching on cliffs
});

// Update LOD based on camera
terrain.update(camera);

CDLOD Algorithm

1. Quadtree Traversal — Start from root tile, subdivide based on camera distance
2. Frustum Culling — Discard tiles outside view frustum
3. LOD Selection — Distance thresholds determine vertex density per tile
4. Geomorphing — Adjacent LOD levels blend smoothly (no popping)
5. GPU Displacement — Vertex shader samples heightmap texture for Y position
6. Normal Computation — Central differences on heightmap for lighting normals

Dependencies

• @web-engine-dev/math — Vectors, matrices, bounding volumes
• @web-engine-dev/renderer — GPU rendering pipeline
• @web-engine-dev/spatial — Frustum culling, quadtree
• @web-engine-dev/assets — Heightmap and texture loading