Feature Library

Terrain shaping

1.06 GPU · 0.28 CPU ms
A still of the Terrain shaping demo
Still
The live demo starts when it’s in view.Switch each shaping pass on or off · choose a close view · drag to orbit

Pure height-function transforms for contour terraces, a carved valley, level pads and a coastline of cliffs and beaches.

Retaining walls and cliff chains return abstract placements; wet benches return shallow pool cells. Compose the functions, then sample once onto your terrain lattice.

What it costs a frame

1.06 ms
0.28 ms
GPU
1.06 ms
CPU, median
0.28 ms
CPU, 95th pct
0.41 ms
Draw calls
33
Weight
Moderate

Measured 19 November 2026 on RTX 4060 Laptop, 13th Gen Intel(R) Core(TM) i9-13900H, Chrome 157, 1920×1080 at 1×. 600 frames × 3 rounds, median kept (rounds ranged GPU 1.06–1.11, CPU 0.28–0.31 ms). What ran: Default shaped coastal hillside: 160 × 160 m at 0.5 m spacing, relief and baked hollow shade, shadow-casting walls, cliffs and two houses, terrace pools, a stream and gently moving sea. No comparison view or control changes. Planners and hollow baking run only on load or edits, outside the measured render frames. Phones: tiers are being measured next.

How steadily it runs on RTX 4060 Laptop · 13th Gen Intel(R) Core(TM) i9-13900H · reference

Typical frame ?
3.22 ms
1% low ?
152 fps
Varies by ?
±0.87 ms
All metricsRTX 4060 Laptop · 13th Gen Intel(R) Core(TM) i9-13900H · reference
p50p95p990.10 ms6.58 ms +
How long each frame took. Most frames sit in the tall bars; a long tail to the right is hitching.

Frames run back to back, each starting once the GPU has finished the last, so frame times show the work itself. They have a floor of about 4–5 ms from the browser’s own scheduling: GPU and CPU ms stay the measure of cost.

Frames

Median (p50) ?
3.22 ms
p95 ?
5.33 ms
p99 ?
6.18 ms
Slowest ?
7.11 ms
Mean ?
3.67 ms
Standard deviation ?
0.87 ms
1% low ?
152 fps
0.1% low ?
141 fps
Hitches ?
3 of 600
Over budget ?
0 of 600

Main thread

Long tasks ?
0
Long frames ?
0
Event-loop delay ?
0.0 / 0.5 / 0.5 ms

Input

No input during this run.

Memory

JavaScript heap ?
75.7 → 83.5 MB
Growth ?
+7.75 MB

Browser

JavaScript a frame ?
0.01 ms
All tasks a frame ?
0.46 ms
Layout / style ?
0.00 / 0.00 ms
Main thread busy ?
13%

Garbage collection

Collections ?
1 (1 minor, 0 major)
Pauses ?
0.5 ms in all, longest 0.5

What it needs

Renders with
WebGPU or WebGLWebGPU where there is one, WebGL2 where there is not.
Your browser
Runs hereNo WebGPU needed
Depends on
three.js 0.187.0No other packages
With an agent
install("terrain-shaping")Your coding agent reads its pitfalls and installs it through the library’s MCP server. Set it up

What it’s for

  1. Cut and fill a hillside into level terraces
  2. Carve a flat valley floor with eased sides
  3. Level circular building footprints
  4. Join a coastal heightfield to cliff walls and gentle beaches

Pitfalls, in brief

  1. All coordinates are Y-up metres; height functions receive X and Z.
  2. Build planners once when inputs change, then sample the final function onto your lattice.
  3. Use finite coordinates and dimensions, positive widths, wavelengths, wall half-thickness and blend distances, and a nondegenerate polygon/path.
  4. Keep hillside slope below step / minWidth where possible (about 0.3 at defaults).
  5. The order of transforms matters.
6 more in brief
  1. A valley sets its floor exactly, including filling land below it inside the floor.
  2. Wall placements retain a 4 m chord profile, 0.8 m thickness and 0.5/1 m nominal heights; scale.y stretches that nominal height.
  3. Cliff placements retain fixed reference ports for 4/6 m profiles, 8 m straights and 90-degree corners.
  4. Coast shaping keeps a 3 m shelf and ground 0.08 m below cliff caps; base defaults to seaLevel - 0.6.
  5. Sample pool depths against the stored/interpolated bed your renderer actually uses, not a different analytic height.
  6. The core has no renderer or three dependency.
11 pitfalls in full, the hook-up guide, the module source and its tests come with the part.

Where it comes from

From HaTac. Adapted from published work, named below.

Hannes Andersson: Source terrain transforms, contour tracing, wall and cliff fitting, pool generation and regression tests.

terrainheightfieldterracesvalleypadscoastcliffsbeachespure functionsno dependencies

Near it in the frame