@plasius/gpu-world-generator 0.0.4

package/docs/biomes.md

@@ -0,0 +1,206 @@
+# Biome Taxonomy (Earth-like)
+
+This list defines macro biomes and their expected sub-biomes. Each sub-biome notes typical surface covers and micro features. Use these as defaults; procedural rules can blend and override locally.
+
+Legend:
+- Surfaces: ground/material layer
+- Features: props, vegetation, structures
+
+## Polar
+- Ice Cap
+  - Surfaces: Ice, Snowpack, Rock
+  - Features: Ice spike, wind-scoured rock
+- Glacier
+  - Surfaces: Ice, Snowpack
+  - Features: Crevasse lines, ice ridges
+- Polar Desert
+  - Surfaces: Snowpack, Gravel, Rock
+  - Features: Sparse boulder fields
+- Frozen Sea
+  - Surfaces: Ice, Water (lead openings)
+  - Features: Pressure ridges, cracks
+
+## Cold Temperate
+- Taiga
+  - Surfaces: Snowpack, Dirt, Rock
+  - Features: Conifer tree, fallen log, shrub
+- Boreal Forest
+  - Surfaces: Dirt, Grass, Snowpack (seasonal)
+  - Features: Conifer tree, bush, moss
+- Cold Steppe
+  - Surfaces: Grass, Dirt, Gravel
+  - Features: Grass tuft, scattered rock
+- Frozen River
+  - Surfaces: Ice, Water
+  - Features: Ice shelf, reeds (edge)
+
+## Temperate
+- Mixed Forest
+  - Surfaces: Dirt, Grass, Leaf litter
+  - Features: Tree (deciduous), bush, fallen log
+- Plains
+  - Surfaces: Grass, Dirt
+  - Features: Grass tuft, flower patch
+- Meadow
+  - Surfaces: Grass
+  - Features: Tall grass, wildflowers
+- River Valley
+  - Surfaces: Grass, Mud, Water
+  - Features: Reeds, riparian trees, boulders
+- Hills
+  - Surfaces: Grass, Rock
+  - Features: Rock outcrop, shrubs
+
+## Arid
+- Desert (Sandy)
+  - Surfaces: Sand, Rock
+  - Features: Dunes, dry shrubs
+- Desert (Rocky)
+  - Surfaces: Rock, Gravel
+  - Features: Boulder fields, mesas
+- Savanna
+  - Surfaces: Grass, Dirt
+  - Features: Sparse trees, shrubs
+- Badlands
+  - Surfaces: Dirt, Rock, Clay
+  - Features: Eroded spires, gullies
+- Oasis
+  - Surfaces: Water, Grass, Mud
+  - Features: Palm trees, reeds
+- Dry Riverbed
+  - Surfaces: Gravel, Sand
+  - Features: Scoured stones
+
+## Tropical
+- Jungle
+  - Surfaces: Dirt, Mud, Leaf litter
+  - Features: Dense trees, vines, ferns
+- Tropical Forest
+  - Surfaces: Grass, Dirt
+  - Features: Tall canopy, shrubs
+- Mangrove
+  - Surfaces: Mud, Water
+  - Features: Mangrove roots, reeds
+- Swamp
+  - Surfaces: Mud, Water
+  - Features: Reeds, stumps, fallen logs
+- Floodplain
+  - Surfaces: Mud, Grass, Water (seasonal)
+  - Features: Reeds, wetland grass
+
+## Alpine
+- Mountain Ridge
+  - Surfaces: Rock, Snowpack
+  - Features: Cliff faces, boulder fields
+- High Meadow
+  - Surfaces: Grass, Rock
+  - Features: Alpine shrubs, grass tuft
+- Scree
+  - Surfaces: Rock, Gravel
+  - Features: Loose stones, talus
+- Snowline
+  - Surfaces: Snowpack, Rock
+  - Features: Sparse shrubs
+- Glacier Valley
+  - Surfaces: Ice, Snowpack, Rock
+  - Features: Moraines
+
+## Volcanic
+- Lava Field
+  - Surfaces: Basalt, Ash
+  - Features: Lava cracks, fumaroles
+- Ash Plain
+  - Surfaces: Ash, Rock
+  - Features: Sparse shrubs, soot drift
+- Geothermal
+  - Surfaces: Rock, Mud
+  - Features: Steam vents, hot springs
+- Obsidian Ridge
+  - Surfaces: Rock (obsidian), Ash
+  - Features: Jagged spires
+
+## Freshwater
+- River
+  - Surfaces: Water, Gravel, Mud
+  - Features: Reeds, ripples, rocks
+- Lake
+  - Surfaces: Water, Mud
+  - Features: Shore reeds, shallow shelf
+- Wetland
+  - Surfaces: Water, Mud, Grass
+  - Features: Reeds, shrubs
+- Marsh
+  - Surfaces: Mud, Water
+  - Features: Tall reeds
+- Bog
+  - Surfaces: Mud, Water, Moss
+  - Features: Stunted trees, pools
+
+## Coastal
+- Beach
+  - Surfaces: Sand, Gravel
+  - Features: Driftwood, tide lines
+- Cliff Coast
+  - Surfaces: Rock, Gravel
+  - Features: Cliff faces, sea spray
+- Estuary
+  - Surfaces: Mud, Water
+  - Features: Reeds, shallow channels
+- Delta
+  - Surfaces: Mud, Water, Sand
+  - Features: Sandbars, channels
+- Reef
+  - Surfaces: Rock, Water
+  - Features: Coral (if supported), shallows
+
+## Urban
+- City Core
+  - Surfaces: Cobble, Road
+  - Features: Buildings, walls, plazas
+- Town
+  - Surfaces: Road, Dirt, Grass
+  - Features: Houses, fences, wells
+- Village
+  - Surfaces: Dirt, Grass
+  - Features: Huts, gardens
+- Castle
+  - Surfaces: Cobble, Rock
+  - Features: Walls, towers, gatehouses
+- Farmland
+  - Surfaces: Dirt, Grass
+  - Features: Crops, irrigation channels
+
+## Underground
+- Caverns
+  - Surfaces: Rock, Gravel, Mud
+  - Features: Stalactite, stalagmite, cave pools
+- Lava Tubes
+  - Surfaces: Basalt, Ash
+  - Features: Lava crust, vent glow
+- Crystal Caves
+  - Surfaces: Crystal, Rock
+  - Features: Crystal spires, reflective shards
+- Subterranean River
+  - Surfaces: Water, Rock, Mud
+  - Features: Underground stream, slick stones
+- Fungal Groves
+  - Surfaces: Mud, Dirt
+  - Features: Giant fungi, spores
+- Mine Shafts
+  - Surfaces: Rock, Dirt
+  - Features: Timber supports, rails, carts, lanterns
+- Sewers
+  - Surfaces: Water, Cobble, Sludge
+  - Features: Grates, brick tunnels, runoff channels
+
+## Cross-Biome Generic Types
+- Rock: outcrops, boulders, cliffs, crystal spires
+- Water: rivers, lakes, puddles, marsh
+- Vegetation: tree, bush, grass tuft, reed
+- Pathing: road, trail, bridge
+
+## Stitching Suggestions
+- Blend macro biomes over 1-2 hex rings using heat/moisture gradients.
+- Sub-biomes should respect parent macro constraints (e.g., no desert inside Polar).
+- Surface cover transitions should be gradual: grass -> dirt -> snowpack.
+- Feature density derived from surface cover + moisture to avoid hard seams.

package/docs/lod-zoning.md

@@ -0,0 +1,22 @@
+# LOD Zoning (Hex Rings)
+
+## Goal
+Use hexagons only for streaming and LOD control around the viewport, not for generation. The world surface is continuous; hexes partition which areas get higher sampling density and richer features.
+
+## Ring Layout
+- Center ring: highest resolution (small step size, full features).
+- Mid ring: medium resolution (reduced step size, fewer features).
+- Far ring: low resolution (coarse step size, minimal features).
+
+## Sampling Strategy
+- Each ring defines a sampling step (meters per sample).
+- The same procedural field functions are evaluated at different step sizes.
+- Cross-fade between rings to reduce popping.
+
+## Caching
+- Cache generated tiles per ring with a key `(ringId, q, r, seed)`.
+- Evict far tiles based on camera movement thresholds.
+
+## Determinism
+- The same input field functions must be used across rings.
+- Only the sampling step and feature density change by ring.

package/docs/plan.md

@@ -0,0 +1,107 @@
+# GPU World Generator Plan
+
+## Summary
+A shader-first world generator that synthesizes continuous surface fields using deterministic mathematics (Mandelbrot/Julia/multibrot stacks). Materials and features are applied in post-surface rule passes (grass/trees/rocks/sand, etc). Hexagons are retained only for LOD zoning and streaming control around the viewport, not for generation.
+
+## Core References
+- `docs/procedural-surface.md` for the deterministic surface field stack (Mandelbrot + warps + blends).
+- `docs/lod-zoning.md` for hex-based LOD rings around the viewport.
+- `docs/biomes.md` for the Earth-like biome taxonomy and sub-biome options.
+- `docs/resources.md` for subsurface resource generation below terrain.
+
+## Surface Field Generation (Shader-First)
+Inputs:
+- World coordinates (x, z) mapped to the complex plane.
+- Seed + global parameters (scale, height, heat, moisture, roughness).
+
+Outputs:
+- Height (0..1), heat (0..1), moisture (0..1), roughness (0..1), rockiness (0..1), water mask (0..1).
+- Cumulative trend band: `0.0..0.2` downward slope, `0.2..0.8` flat, `0.8..1.0` upward slope.
+- Feature/obstacle mask (0..1).
+- Foliage density mask (0..1).
+
+Shader stages (field stack):
+1. Base fractal field (Mandelbrot/Julia or multibrot, smooth iteration count).
+2. Domain warping to break symmetry (secondary fractal offsets).
+3. Multiplicative blends to combine large/mid/small detail.
+4. Ridge/valley shaping (abs/threshold transforms).
+5. Optional erosion heuristics (slope/curvature approximations).
+
+## Rule Passes (Material + Features)
+1. Hydrology: water fills local minima, flattens surface, and follows flow paths.
+2. Material selection: slope + height + moisture -> rock/sand/grass/mud/ice.
+3. Feature placement: trees/rocks/props based on material + local noise.
+4. Structural overlays: towns/roads/castles (deterministic hash rules).
+
+## LOD Zoning (Hex Rings Around Viewport)
+- Hexes define streaming and LOD rings only.
+- Nearest ring: highest sample resolution (smallest step).
+- Mid ring: medium resolution.
+- Far ring: low resolution + simplified materials/features.
+- Cross-fade or blend across ring boundaries to avoid popping.
+
+## Biome Hierarchy (Suggested)
+The same cell is classified at multiple levels. Each stage constrains the next to keep seams predictable.
+
+See `docs/biomes.md` for the full Earth-like biome taxonomy and sub-biome options.
+See `docs/resources.md` for subsurface resource generation below terrain.
+
+### Level 0: Macro Biomes (regional)
+- Polar (ice cap, glacier belt)
+- Cold Temperate (taiga, boreal forest)
+- Temperate (mixed forest, plains)
+- Arid (desert, savanna)
+- Tropical (jungle, mangrove)
+- Alpine (mountainous, highlands)
+- Volcanic (lava fields, ash plains)
+- Freshwater (river/lake basins)
+- Coastal/Marine (coastline, estuary)
+- Urban (major settlement regions)
+- Underground (caverns, tunnels)
+
+### Level 1: Sub-biomes (local terrain)
+Examples by macro:
+- Polar: Ice, Snow, Tundra
+- Cold Temperate: Tundra, Pine Forest, Frozen River
+- Temperate: Plains, Mixed Forest, River, Hills
+- Arid: Savanna, Desert, Oasis, Dry Riverbed
+- Tropical: Jungle, Swamp, River, Mangrove
+- Alpine: Mountainous, Cliff, Scree, Snowline
+- Volcanic: Lava, Basalt, Ash, Geothermal
+- Freshwater: River, Lake, Wetland
+- Coastal/Marine: Beach, Cliffs, Reef, Estuary
+- Urban: City, Town, Village, Castle
+
+### Level 2: Surface Cover (ground/material)
+- Grass, Dirt, Sand, Rock, Gravel, Snowpack, Ice, Mud, Ash, Cobble, Road
+- Water surfaces: River, Lake, Coastal surf
+
+### Level 3: Micro Features (prop/placement)
+- Tree, Bush, Grass Tuft, Reed, Rock, Boulder, Water Ripple, Ice Spike
+- Structures: Hut, Wall, Bridge, Gate, Tower, Ruin
+
+### Stitching Rules
+- Macro boundaries blend over 1-2 hex rings using weighted masks (heat/moisture/height).
+- Sub-biomes inherit and override surface covers gradually (e.g., grass -> dirt -> snow).
+- Feature density derived from surface cover and moisture to avoid hard seams.
+## Terrain Targets (Initial)
+- Tundra, Savanna, River, City, Village, Ice, Snow, Mountainous, Volcanic, Road, Town, Castle.
+- Additional neutral base: Plains (default).
+
+## Particle + Shader Attachments
+- Tree shader: base mesh + leaf instancing.
+- Particle system tags: e.g., `leaves_falling` attached to Tree biome + season.
+- Local effects triggered by biome + heat/moisture (e.g., snow drift, ash fall).
+
+## Package Deliverables
+- WGSL field stack for deterministic surface generation.
+- TypeScript helpers to sample fields and apply rule passes.
+- LOD zoning manager (hex rings) for streaming control.
+
+## Development Steps
+1. Add deterministic fractal field stack (Mandelbrot/Julia/multibrot).
+2. Add domain warp + multiplicative blending controls.
+3. Implement hydrology + material rule passes.
+4. Add feature placement (trees/rocks/props) based on rules.
+5. Add LOD zoning manager (hex rings) and cross-fade.
+6. Integrate in demo + shader tuning pass.

package/docs/procedural-surface.md

@@ -0,0 +1,73 @@
+# Procedural Surface (Deterministic Math)
+
+## Goal
+Generate height/heat/moisture/roughness fields from deterministic mathematics (Mandelbrot/Julia/multibrot) and then apply rule-based materials + features. The same `(x, z, seed)` input always yields the same surface, enabling reproducible worlds.
+
+## Coordinate Mapping
+- Map world `(x, z)` to complex plane `c = (u, v)`.
+- Use seeded transforms to avoid symmetry:
+  - `u = (x * scale + offsetX) * skewX + warpX`
+  - `v = (z * scale + offsetZ) * skewZ + warpZ`
+- Keep scale separate per band: large (continental), mid (regional), small (local).
+
+## Fractal Field Stack
+Each layer returns a smooth iteration count `f(x, z)` in `[0, 1]`.
+
+1. Base set (Mandelbrot or Julia):
+   - `z = 0; z = z^p + c` or `z = z^p + k` for Julia.
+   - Use smooth iteration for continuity.
+2. Domain warp (secondary fractal):
+   - `c' = c + warpStrength * vec2(f2(x, z), f3(x, z))`.
+3. Multiplicative blend:
+   - `height = clamp(fA^a * fB^b * fC^c, 0, 1)`.
+4. Ridged transform:
+   - `ridge = 1 - abs(2 * f - 1)`.
+5. Composite fields:
+   - `heat = mix(fHeat1, fHeat2, ridge)`
+   - `moisture = mix(fMoist1, fMoist2, fMask)`
+
+## Derived Maps
+From the height field:
+- Slope (for rock exposure).
+- Curvature (for valleys vs ridges).
+- Flow accumulation (for rivers/wetlands).
+- Roughness (for biome texture and LOD decisions).
+
+## Style Mixing (Macro Map)
+To avoid uniform terrain, use a low-frequency macro map to blend between
+two different height styles per region.
+- Style A: earth-like dramatic (ridged multifractal, smoother slopes).
+- Style B: surreal (terracing + crater basins + sharper ridges).
+
+`styleMask = macroMap(x, z)` → `height = mix(styleA, styleB, styleMask)`
+
+## Signed Height Pipeline
+Heights can extend outside `[0, 1]` internally (e.g. `[-0.35..1.6]`):
+- `rawHeight` drives mesh elevation.
+- `height01 = clamp(rawHeight, 0, 1)` is used for heat/moisture/water/biomes.
+
+## Terraces + Craters
+- **Terracing**: quantize height into steps with smooth interpolation.
+- **Crater field**: hashed radial basins that carve the surface.
+- These modifiers are blended in as part of style B and remain deterministic.
+
+## Rule Passes (Post Surface)
+- Water:
+  - Flatten water at local minima and flow along gradients.
+  - Beach/silt where slope is low and moisture high.
+- Rock exposure:
+  - High slope + high roughness -> rock.
+- Vegetation:
+  - Moisture + low slope + moderate heat -> grass/forest.
+- Sand:
+  - High heat + low moisture + low slope -> sand.
+
+## Determinism
+All parameters (seed, scale, warps) must be explicit.
+No random calls without a seed.
+
+## Suggested Parameters (Starter)
+- Iterations: 24–96 (based on LOD band).
+- Multibrot exponent `p`: 2.0–3.5.
+- Warp strength: 0.05–0.25.
+- Blend exponents: 0.8–1.4.

package/docs/resources.md

@@ -0,0 +1,55 @@
+# Subsurface Resources (Below Terrain)
+
+This defines what a player might find when digging below the surface. The goal is to generate a resource profile per hex cell based on macro biome, sub-biome, and depth bands.
+
+## Depth Bands (Suggested)
+- 0-1 m: Litter/topsoil (organic debris, roots)
+- 1-5 m: Subsoil (clay, compacted dirt, small stones)
+- 5-30 m: Soft rock/strata (limestone, sandstone, shale)
+- 30-200 m: Hard rock (granite, basalt, metamorphic)
+- 200+ m: Deep strata (rare ores, geothermal pockets)
+
+## Resource Categories
+- Soil/organic: topsoil, peat, compost
+- Stone/common: limestone, sandstone, shale, granite, basalt
+- Metals/common: iron, copper, tin
+- Metals/rare: silver, gold, platinum
+- Crystals/minerals: quartz, crystal clusters, geodes
+- Volatiles: coal, sulfur, gas pockets
+- Water: aquifers, underground rivers, brine
+- Special: relics, ruins, lost tech (gameplay-dependent)
+
+## Resource Rules (High-Level)
+- Each hex cell has a resource profile per depth band (density + rarity).
+- Macro biome influences baseline probability (e.g., Volcanic -> basalt/sulfur; Arid -> sandstone; Polar -> permafrost/ice lenses).
+- Sub-biome refines (e.g., River -> aquifers; Mountainous -> ore veins; Urban -> ruins/utility tunnels).
+- Height + heat + moisture bias ore types and water tables.
+
+## Example Resource Bias by Macro Biome
+- Polar: ice lenses, permafrost, low metal density.
+- Cold Temperate: iron + copper pockets, shallow aquifers.
+- Temperate: balanced stone + water, moderate metal density.
+- Arid: sandstone, salt, deep water.
+- Tropical: rich organic topsoil, shallow water, softer rock.
+- Alpine: high ore density, hard rock, sparse water.
+- Volcanic: basalt, sulfur, obsidian, geothermal pockets.
+- Freshwater: high water tables, sedimentary rock.
+- Coastal: brine, sand/clay layers.
+- Urban: utility tunnels, debris layers, old foundations.
+- Underground: mineral-rich, crystal clusters, cave water.
+
+## Generation Approach (Per Cell)
+1. Compute base strata material via (q, r, depth) noise.
+2. Apply macro biome bias table (weights per resource category).
+3. Apply sub-biome overrides (e.g., river -> water table upshift).
+4. Run ore vein placement (3D noise thresholds + connected blobs).
+5. Output per-depth resource layers (density, rarity, type).
+
+## Data Model (Proposed)
+- ResourceLayer: { depthStartM, depthEndM, materialType, density, rarity }
+- VeinNode: { center, radiusM, resourceType, richness }
+- Aquifer: { depthM, thicknessM, saturation }
+
+## Stitching Notes
+- Blend resource profiles across hex edges to avoid sudden changes.
+- Ensure veins can cross neighboring hexes (connected components).

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@plasius/gpu-world-generator",
+  "version": "0.0.4",
+  "description": "GPU-assisted world generation with hex-grid terrain synthesis.",
+  "type": "module",
+  "sideEffects": false,
+  "private": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "files": [
+    "dist",
+    "src",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./terrain.wgsl": "./dist/terrain.wgsl",
+    "./field.wgsl": "./dist/field.wgsl",
+    "./fractal-prepass.wgsl": "./dist/fractal-prepass.wgsl",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup && cp src/terrain.wgsl dist/terrain.wgsl && cp src/field.wgsl dist/field.wgsl && cp src/fractal-prepass.wgsl dist/fractal-prepass.wgsl",
+    "test": "node --test",
+    "test:coverage": "c8 --reporter=lcov --reporter=text node --test"
+  },
+  "dependencies": {
+    "@plasius/gpu-worker": "^0.1.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "c8": "^10.1.3"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Plasius-LTD/gpu-world-generator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Plasius-LTD/gpu-world-generator/issues"
+  },
+  "homepage": "https://github.com/Plasius-LTD/gpu-world-generator#readme"
+}