# metaverse-terrain Three.js terrain library with PBR texture blending, animated water, and heightmap brush editing. `TerrainRegion` owns the terrain mesh, TSL node materials, and height data. Your app owns the scene graph, camera, input, and raycasting. ## Install **npm** ```bash npm install metaverse-terrain three ``` Requires `three` >= 0.160 as a peer dependency. The runtime uses Three.js Shading Language (TSL), so host apps must use `WebGPURenderer` from `three/webgpu` (with Three's WebGL fallback where available). Use with Vite, Webpack, or any bundler — no import map needed. **jsDelivr** No install step. Load from [cdn.jsdelivr.net/npm/metaverse-terrain](https://cdn.jsdelivr.net/npm/metaverse-terrain/) in the browser using an import map (see below). --- ## Using with jsDelivr Browsers cannot resolve bare imports like `'metaverse-terrain'` on their own. Add an **import map** in your HTML, then load your app in a **` ``` Serve over HTTP (not `file://`). The snippets below go inside that ` ``` ### Painting The library does not handle pointer events. Raycast the terrain, then call `paintAt`: ```js import { TerrainRegion, getTerrainHitFromPointer } from 'metaverse-terrain'; const TEXTURE_BASE = 'https://cdn.jsdelivr.net/npm/metaverse-terrain/texture'; const textures = { /* sand, grass, rock, snow, water — see above */ }; const raycaster = new THREE.Raycaster(); const pointer = new THREE.Vector2(); const canvas = renderer.domElement; const region = new TerrainRegion({ textures }); let isPainting = false; canvas.addEventListener('pointerdown', (event) => { const hit = getTerrainHitFromPointer( region, canvas, camera, raycaster, pointer, event.clientX, event.clientY, ); if (!hit) return; isPainting = true; region.beginStroke(); region.paintAt(hit.point, { temporaryLower: event.shiftKey }); }); canvas.addEventListener('pointermove', (event) => { if (!isPainting) return; const hit = getTerrainHitFromPointer( region, canvas, camera, raycaster, pointer, event.clientX, event.clientY, ); if (hit) region.paintAt(hit.point, { temporaryLower: event.shiftKey }); }); canvas.addEventListener('pointerup', () => { region.endStroke(); isPainting = false; }); ``` ### Configuration ```js import { TerrainRegion } from 'metaverse-terrain'; const region = new TerrainRegion({ textures, regionSize: 256, seed: 29, waterLevel: 28, textureDensity: 10, }); region.setBrushMode('raise'); region.setBrushRadius(8); region.setWaterLevel(24); region.downloadHeightmap(); ``` ### Optional DOM helpers ```js import { bindTerrainPainting, bindTextureDrop } from 'metaverse-terrain'; bindTerrainPainting(region, { domElement: canvas, camera, raycaster, pointer }); bindTextureDrop(region); // needs [data-texture-drop="grass"] elements in HTML ``` --- ## Using with npm ```js import * as THREE from 'three/webgpu'; import { TerrainRegion, loadPBRTextureSet } from 'metaverse-terrain'; import sand from 'metaverse-terrain/texture/terrain-sand.png'; import grass from 'metaverse-terrain/texture/terrain-grass.png'; import rock from 'metaverse-terrain/texture/terrain-rock.png'; import snow from 'metaverse-terrain/texture/terrain-snow.png'; import water from 'metaverse-terrain/texture/terrain-water.png'; import sandMetal from 'metaverse-terrain/texture/terrain-sand_metal.png'; import sandRoughness from 'metaverse-terrain/texture/terrain-sand_roughness.png'; import sandNormal from 'metaverse-terrain/texture/terrain-sand_normal.png'; import sandAO from 'metaverse-terrain/texture/terrain-sand_ao.png'; // ... same pattern for grass, rock, snow, water const pbrTextures = await loadPBRTextureSet({ sand: { metal: sandMetal, roughness: sandRoughness, normal: sandNormal, ao: sandAO }, // grass, rock, snow, water ... }); const region = new TerrainRegion({ textures: { sand, grass, rock, snow, water }, pbrTextures, seed: 42, }); scene.add(region.group); ``` Omit `pbrTextures` for albedo-only rendering. --- ## API | Export | Purpose | |--------|---------| | `TerrainRegion` | Terrain mesh, water, heightmap, brush state | | `loadPBRTextureSet` | Load and pack PBR maps (metal, roughness, normal, AO → MRAO) | | `getTerrainHitFromPointer` | Screen coords → terrain intersection | | `bindTerrainPainting` | Wire pointer events to brush painting | | `bindTextureDrop` | Drag-and-drop images onto texture swatches | | `TERRAIN_TEXTURE_LAYERS` | `['sand', 'grass', 'rock', 'snow', 'water']` | | `PBR_CHANNELS` | `['metal', 'roughness', 'normal', 'ao']` | | `DEFAULT_TEXTURE_HEIGHTS` | Default height blend thresholds | **`TerrainRegion` methods** | Method | Description | |--------|-------------| | `raycast(raycaster)` | Intersect terrain mesh | | `paintAt(point, options?)` | Apply brush and emit `onHeightmapChange` | | `setBrushMode` / `setBrushRadius` / `setBrushStrength` | Brush settings | | `setWaterLevel` / `setWaterEnabled` | Water plane | | `setTextureDensity` | Texture tiling density | | `setTextureHeights` | Sand/grass/rock/snow height bands | | `setNormalStrength` / `setTerrainAOIntensity` | PBR normal and AO intensity | | `setPBREnabled` / `setWaterIOR` | PBR water toggle and index of refraction | | `setTerrainTexture(layer, source)` | Replace a texture at runtime | | `randomize(seed?)` / `level(height?)` | Regenerate or flatten heightmap | | `drawHeightmapPreview(canvas)` / `downloadHeightmap()` | Export heightmap | | `update(elapsedTime)` | Animate water | | `dispose()` | Free GPU resources | TypeScript types ship in `index.d.ts`. ## Demo apps ```bash git clone https://github.com/richardanaya/metaverse-terrain.git cd metaverse-terrain python3 -m http.server 8080 ``` - [Editor](http://localhost:8080/example/editor/) — full brush editor with PBR and HDRI lighting - [Minimal](http://localhost:8080/example/simple/) — smallest PBR integration ## License MIT — Richard Anaya. See [LICENSE](LICENSE). Reference textures: MIT — Richard Anaya. See [ASSET_LICENSES.md](ASSET_LICENSES.md).