Procedural Terrains

A shader-driven procedural terrain generator and editor built with React + Vite + Three.js (WebGL2).

Height, normals and biome colors are computed on the GPU — there is no baked CPU heightmap driving the live view. The app ships three world modes (switchable from the top bar):

Mode	What it is
Tile	Fixed terrain board with per-chunk LOD — best for painting, multi-tile layouts and exports
Infinite World	Streamed chunk grid around the camera with FPS walk / plane exploration
Planet	Cube-sphere procedural planet with atmosphere, volumetric clouds and orbit camera

Run

npm install
npm run dev

The dev server starts on http://localhost:6061 and is also reachable on your local network (Vite listens on all interfaces and prints the LAN URL, e.g. http://192.168.x.x:6061). If port 6061 is already in use, Vite picks the next free port.

Production build: npm run build (output in dist/), preview it with npm run preview.

Optional accounts API

Login and registration are backed by an independent, self-hostable Node.js/MySQL service in api/. The editor remains local-first and fully usable without an account.

For local development, copy both environment examples and start the frontend and API in separate terminals:

cp .env.example .env
cp api/.env.example api/.env
npm --prefix api install
npm run dev
npm run dev:api

Run npm run migrate:api once MySQL is configured. Classic Linux, PM2, MySQL and Nginx deployment instructions are in api/README.md.

Architecture

The WebGL engine is framework-agnostic (src/engine/); the editor UI is React (src/components/). They talk through Engine methods + a callbacks object — React mirrors the engine's parameter state and renders the side-panel controls.

Area	Key files
Core	src/engine/Engine.js — renderer, scene, param→uniform plumbing, save/load, undo state
Tile board	src/engine/terrain/TerrainBoard.js, ChunkGeometry.js, BoardPlinth.js
Infinite world	src/engine/terrain/InfiniteWorld.js — streamed chunks, triangle budget, behind-camera culling
Planet	src/engine/terrain/PlanetWorld.js, PlanetMaterial.js, PlanetOrbitControls.js
Noise stack	src/engine/terrain/noise/NoiseStack.js, noiseStackCodegen.js — layered, serializable noise layers compiled to GLSL
Shaders	src/engine/terrain/terrainGLSL.js, TerrainMaterial.js, WaterMaterial.js
Water	src/engine/water/WaterSystem.js, RealisticWaterMaterial.js, UnderwaterEffect.js
Sky & clouds	src/engine/sky/ProceduralSky.js, CloudSlabLayer.js, PlanetCloudChunks.js, TimeOfDay.js
Style	src/engine/style/PlanetStyleManager.js, ColorPalette.js
Paint	src/paint/PaintModeManager.js — height / biome / props brush layers (Tile mode)
Export	src/engine/terrain/TerrainExporter.js, PlanetExporter.js
UI	src/App.jsx, src/components/panels/index.jsx — schema-driven side panels, settings search, performance overlay

Key properties

• Deterministic: terrain is a pure function of (world XZ, seed, params). The seed drives a domain offset via a mulberry32 PRNG; Math.random() is never used for shape.
• Layered noise: a stack of typed noise layers (add, carve, replace, …) is codegen'd into the terrain shader and serializes with every save.
• No cracks: chunk geometries carry skirt rings dropped in the vertex shader so adjacent chunks at different LODs never show gaps.
• Live editing: most sliders map to shader uniforms — only chunk count/size, tile layout, planet radius and a few structural keys trigger a geometry rebuild.
• Camera never shapes terrain: LOD is view-dependent; the height field is not.
• Undo / redo: full project state (params, tiles, paint layers) with Ctrl+Z / Ctrl+Y.
• Save / load: seed + all parameters as JSON from the top bar.

Tile mode extras

• Multi-tile assembly: place tiles on a grid to build larger landscapes; export merged or per-tile.
• Square or circle layout: circle mode clips terrain to a disk, supports ring expansion, and renders a radial wall that follows the terrain silhouette.
• Paint mode: brush height, rivers, biomes and procedural props onto the board.
• Real-world heightmaps: import location-based elevation data (preview, replace or blend).
• Close-range detail layer: extra surface detail near the camera in Tile mode.

Controls

Editor camera (Tile mode)

• Left-drag — pan across the board (clamped)
• Right-drag — orbit
• Scroll — zoom
• Bottom toolbar: top-down / angled / reset camera

Exploration (Infinite World & Planet)

• Bottom toolbar Explore menu: Walk (FPS) or Plane (fly-through)
• Touch controls on mobile while exploring

Shortcuts

• Ctrl+K — search all settings
• Ctrl+Z / Ctrl+Y — undo / redo
• Ctrl+Shift+P — developer performance overlay (also via the FPS badge in the status bar)

Exports

Quick actions (Export panel):

• Screenshot — PNG of the current viewport
• Heightmap — orthographic grayscale bake from the same shader

Full export (ZIP with optional contents):

• Terrain mesh as GLB/GLTF or OBJ (configurable resolution, skirts, base slab). Multi-tile square boards can export as one combined mesh or as per-tile packages in the ZIP.
• Baked color, normal and heightmap textures
• Biome splat map, collision mesh, water surface mesh
• Water masks (depth, shoreline, foam) and preset JSON for re-import

Production presets

The Export panel includes a preflight Production Check and target presets for Unity Terrain, Unreal Landscape, Godot Terrain3D, Blender Scene, and Three.js Viewer Assets. Engine presets package files into import-oriented folders with a terrain.json and README.txt; Unity and Unreal use a little-endian unsigned 16-bit raw heightmap (.raw / .r16). The checker blocks invalid asset selections and flags high-memory maps or missing water masks before the GPU bake begins.

Planet mode has a dedicated planet exporter with cubemap height baking.

Local projects

The home screen is a local-first project hub. Create a blank terrain or start from Island, Mountain Range, or Desert templates; then use Save in the editor to persist the project in the browser. Projects include versioned terrain data, metadata, an editor-captured thumbnail, and a recent-project entry. Storage uses IndexedDB with a localStorage fallback, and the Projects button reopens the hub. Existing seed JSON files can still be imported.

Performance notes

Normals are finite-differenced per fragment (multiple height evaluations per pixel), which keeps distant terrain crisp at low geometric LOD. The Performance panel offers GPU-tier detection, quality presets, LOD budgets and renderer options. On weaker GPUs, lower the pixel ratio, reduce octaves/layer count, or switch to a lighter water quality mode.