Terrain System

🏔️ Terrain System

Strata’s terrain system uses Signed Distance Functions (SDF) and the Marching Cubes algorithm to generate infinite, explorable 3D terrain with caves, overhangs, and multi-biome blending.

Quick Start

import { Terrain } from '@strata-game-library/core';

<Terrain
  biomes={['grassland', 'mountain', 'desert']}
  resolution={64}
  size={256}
/>

How It Works

1. Signed Distance Functions (SDF)

Terrain is defined as a mathematical function that returns the distance to the surface:

• Negative values: Inside solid terrain
• Positive values: Outside (air)
• Zero: The surface

import { sdTerrain, sdCaves, sdRock } from '@strata-game-library/core';

function customTerrainSDF(point: [number, number, number]): number {
  // Base terrain heightmap
  let d = sdTerrain(point, {
    amplitude: 50,
    frequency: 0.02
  });

  // Subtract caves
  d = Math.max(d, -sdCaves(point, {
    density: 0.1,
    size: 5
  }));

  // Add rock formations
  d = Math.min(d, sdRock(point, [20, 0, 20], 8));

  return d;
}

2. Marching Cubes

The marching cubes algorithm converts the SDF into a triangle mesh:

import { generateTerrainChunk } from '@strata-game-library/core';

const geometry = generateTerrainChunk({
  position: [0, 0, 0],
  size: 32,
  resolution: 64,
  sdfFunction: customTerrainSDF
});

3. Biome Blending

Multiple biomes blend smoothly based on noise:

import { getBiomeAt, getTerrainHeight } from '@strata-game-library/core';

const biome = getBiomeAt(x, z, biomeConfig);
const height = getTerrainHeight(x, z, biome);

Components

<Terrain>

The main terrain component with automatic chunking and LOD.

import { Terrain } from '@strata-game-library/core';

<Terrain
  // Biome configuration
  biomes={['grassland', 'mountain', 'desert', 'snow']}
  biomeScale={0.001}

  // Terrain shape
  amplitude={80}
  frequency={0.015}
  octaves={6}

  // Mesh quality
  resolution={64}
  size={256}

  // Chunks
  chunkSize={32}
  viewDistance={3}

  // Position
  position={[0, 0, 0]}
/>

Props

Prop	Type	Default	Description
biomes	string[]	['default']	Biome types to include
biomeScale	number	0.001	Scale of biome noise
amplitude	number	50	Maximum terrain height
frequency	number	0.02	Base noise frequency
octaves	number	6	Noise detail levels
resolution	number	64	Mesh resolution
size	number	256	Terrain size in units
chunkSize	number	32	Size of each chunk
viewDistance	number	3	Chunks to render

<TerrainChunk>

Individual terrain chunk for custom chunking systems:

import { TerrainChunk } from '@strata-game-library/core';

<TerrainChunk
  position={[32, 0, 0]}
  size={32}
  resolution={64}
  sdf={customSDF}
/>

Biome Types

Built-in Biomes

Biome	Description	Colors
grassland	Rolling green hills	Green, brown
mountain	Rocky peaks	Gray, white
desert	Sandy dunes	Tan, orange
snow	Frozen tundra	White, blue
forest	Dense woodland	Dark green
swamp	Wetlands	Brown, green
volcanic	Lava terrain	Black, red
beach	Coastal sand	Tan, white

Custom Biomes

import { createBiome } from '@strata-game-library/core';

const customBiome = createBiome({
  name: 'alienPlanet',
  colors: {
    low: '#7b2cbf',    // Purple at sea level
    mid: '#9d4edd',    // Lighter purple
    high: '#c77dff',   // Pale purple peaks
    cliff: '#5a189a'   // Dark purple cliffs
  },
  terrainShape: {
    amplitude: 100,
    frequency: 0.01,
    sharpness: 0.8
  },
  vegetation: {
    trees: false,
    grass: true,
    grassColor: '#e0aaff'
  }
});

Core Functions

SDF Terrain Functions

import {
  sdTerrain,
  sdCaves,
  sdRock,
  sdPlateaus,
  calcNormal
} from '@strata-game-library/core';

// Basic terrain heightfield
const d1 = sdTerrain(point, config);

// Cave systems
const d2 = sdCaves(point, { density: 0.1 });

// Rock formations
const d3 = sdRock(point, center, radius);

// Flat plateaus
const d4 = sdPlateaus(point, { height: 30, size: 50 });

// Calculate surface normal
const normal = calcNormal(point, sdfFunction);

Noise Functions

import { noise3D, fbm, warpedFbm } from '@strata-game-library/core';

// Simple 3D noise
const n1 = noise3D(x, y, z);

// Fractal Brownian Motion
const n2 = fbm(x, y, z, {
  octaves: 6,
  persistence: 0.5,
  lacunarity: 2.0
});

// Warped noise for more organic shapes
const n3 = warpedFbm(x, y, z, {
  octaves: 4,
  warpStrength: 0.5
});

Geometry Generation

import {
  marchingCubes,
  createGeometryFromMarchingCubes,
  generateTerrainChunk
} from '@strata-game-library/core';

// Low-level marching cubes
const { vertices, indices } = marchingCubes(sdf, bounds, resolution);

// Create Three.js geometry
const geometry = createGeometryFromMarchingCubes({
  bounds: { min: [-50, -50, -50], max: [50, 50, 50] },
  resolution: 64,
  sdf: terrainSDF
});

// Complete terrain chunk with materials
const chunk = generateTerrainChunk({
  position: [0, 0, 0],
  size: 32,
  resolution: 64,
  sdfFunction: terrainSDF,
  biomeFunction: getBiomeAt
});

Texturing

Triplanar Mapping

Strata uses triplanar mapping to avoid texture stretching on steep surfaces:

import { createTriplanarMaterial } from '@strata-game-library/core';
import { useLoader } from '@react-three/fiber';
import { TextureLoader } from 'three';

// Load textures using R3F's useLoader hook
const grassTexture = useLoader(TextureLoader, '/textures/grass.jpg');
const rockTexture = useLoader(TextureLoader, '/textures/rock.jpg');
const sandTexture = useLoader(TextureLoader, '/textures/sand.jpg');
const snowTexture = useLoader(TextureLoader, '/textures/snow.jpg');

const material = createTriplanarMaterial({
  textures: {
    grass: grassTexture,
    rock: rockTexture,
    sand: sandTexture,
    snow: snowTexture
  },
  blendSharpness: 4,
  textureScale: 0.1
});

Height-Based Blending

import { createHeightBlendMaterial } from '@strata-game-library/core';

const material = createHeightBlendMaterial({
  levels: [
    { height: 0, texture: sandTexture },
    { height: 20, texture: grassTexture },
    { height: 50, texture: rockTexture },
    { height: 80, texture: snowTexture }
  ],
  blendRange: 10
});

Performance Tips

1. LOD (Level of Detail)

<Terrain
  lodLevels={[
    { distance: 0, resolution: 64 },
    { distance: 100, resolution: 32 },
    { distance: 300, resolution: 16 }
  ]}
/>

2. Chunk Loading

<Terrain
  viewDistance={2}           // Fewer chunks
  chunkSize={64}             // Larger chunks
  loadingPriority="distance" // Load nearest first
/>

3. GPU Instancing for Details

<Terrain>
  <TerrainDetails
    rocks={1000}
    pebbles={5000}
    useInstancing
  />
</Terrain>

Examples

Island Terrain

<Terrain
  biomes={['beach', 'grassland', 'mountain']}
  shape="island"
  size={512}
  waterLevel={0}
/>

Cave System

You can create terrain with caves by composing the Terrain component with cave SDF functions:

import { Terrain } from '@strata-game-library/core';
import { sdTerrain, sdCaves } from '@strata-game-library/core';

// Define a custom SDF that combines terrain with caves
function terrainWithCaves(point: [number, number, number]): number {
  // Base terrain
  let d = sdTerrain(point, { amplitude: 50, frequency: 0.02 });

  // Subtract cave system (negative SDF = hollow space)
  const caves = sdCaves(point, {
    density: 0.15,
    minSize: 3,
    maxSize: 15,
    connectivity: 0.7
  });
  d = Math.max(d, -caves);

  return d;
}

// Use the custom SDF with Terrain component
<Terrain
  sdf={terrainWithCaves}
  size={256}
  resolution={64}
/>

Floating Islands

<Terrain
  shape="floatingIslands"
  islandCount={5}
  islandSize={[50, 100]}
  islandHeight={[20, 80]}
/>

Live Demo

See the interactive terrain demo running live in your browser.

View Live Demo | View Source

Related

• Vegetation - Add plants to terrain
• Water - Add water bodies
• Terrain Shaders - Custom terrain shaders
• Terrain Presets - Ready-to-use configurations