Terrain
2D heightmap-based elevation model with contour visualization for road placement and site grading.
Implementation Status: Core prototype complete (2026-08-18). Heightmap + GPU-driven CDLOD terrain mesh (zero CPU vertex/index rebuilds, static patch geometry displaced from an R32Float heightmap texture), semantic layers, GPU water-flow compute, contour and slope visualization, road grade evaluation, and cut/fill grading cost all implemented and tested under game/src/engine/terrain/, with live rendering wired into main scene. Frustum culling runs as a WebGPU compute pass over the CDLOD quadtree, writing visible instances into an indirect draw buffer with zero CPU overhead. Terraforming brush strokes (raise/lower, level, smooth) dispatch as GPU compute and are undoable through the survey history stack. Solid 30+ fps at high-altitude (2.4km) camera views over the full 5.12km×5.12km map. Erosion simulation, tunnels, and seasonal flooding remain post-launch.
Data Model: Hybrid Heightmap + Semantic Layers
Surface: A 2D heightmap grid where each cell stores elevation (float). This is the primary renderable geometry — roads, buildings, and camera place against this surface. Same efficiency and authoring simplicity as SimCity 4 / Cities: Skylines.[1]
- Resolution: TBD grid size and cell dimensions (e.g., 1024×1024 cells at 16m/cell = 16km×16km map)
- Range: Elevation from sea level (0m) to maximum playable height; default sea level at 40m
- Format: 8- or 16-bit greyscale image for authoring; internal representation as dense float grid for runtime
Semantic data layers: Alongside the heightmap, maintain additional per-cell grids capturing terrain attributes that influence simulation and gameplay. Each layer is computed from the heightmap and player edits via GPU compute shaders:
- Water flow: Flow direction and accumulated runoff per cell (computed from slope + precipitation); drives water routing and erosion
- Water table: Groundwater depth below surface (affected by water flow, precipitation, drainage); constrains excavation and affects building foundation cost
- Buildability: Per-cell suitability (slope ≤ threshold, not flooded, not on protected land); used by zoning and development simulation
- Ground pollution: Contamination level from industry or accidents; affects land value and zoning eligibility
- Water pollution: Per-waterbody contamination (separate layer for rivers/lakes); flows downstream via water-flow layer
- Land value: Baseline desirability (affected by slope, water proximity, pollution, view); modulated by demand simulation and player zoning
Sub-surface sparse voxels (future): A sparse 3D voxel grid under the heightmap stores volumetric terrain data: soil/rock type, cut/fill history, utility lines, and (post-launch) tunnel geometry. Cut/fill operations update both the heightmap (visual surface) and the sub-surface voxel grid, propagating changes to all dependent data layers.[1]
Editor Visualization
- Contour lines: Display terrain contours at fixed elevation intervals (e.g., every 10m) to guide road placement and site grading
- Grid overlay: Construction grid snapped to terrain contours; road centerlines snap to grid + contour intersections with adjustable tolerance
- Slope visualization: Optional multi-stop color ramp showing slope steepness to identify buildable sites and constrain road grades, matching municipal planning suitability and in-game road class limits:
| Slope Range | Classification | Planning Suitability & Road Limits | Target Color |
|---|---|---|---|
| 0% – 5% | Flat / Optimal | All intensive development; suited for Highways (max 8%) and Collectors (max 10%). | Green (hsl(140, 70%, 45%)) |
| 5% – 10% | Moderate | Standard residential/commercial; Collector limit (10%) and Local streets (max 12%). | Yellow (hsl(50, 95%, 50%)) |
| 10% – 15% | Challenging | Marginal development requiring grading; Alley limit (15%) and Unpaved (max 20%). | Orange (hsl(28, 95%, 52%)) |
| 15% – 20%+ | Severe / Critical | Steep slope ordinances; road grade violations, high earthwork and erosion hazard. | Red (hsl(0, 80%, 55%)) |
- Height labels: Sample elevation values at cursor position during editing
Road Interaction & Grading
Road placement and geometry are constrained by terrain and its semantic layers:
- Road sketching occurs over terrain; centerline can follow contours or climb slopes
- Grade limits per road class enforce realistic slope constraints (e.g., freeways ≤ 6%, local roads ≤ 12%)
- Vertical alignment (profile view) shows road grade relative to ground elevation
- Water table constraint: Grading below water table increases foundation cost and flooding risk; player can see water table depth in inspector
- Cut/fill operations: Player can raise/lower terrain to grade a site. Cut/fill updates the heightmap surface and propagates to water-flow and water-table layers via compute shader; changes flow routing and may expose groundwater
- Cut/fill volumes estimated for grading cost; costs scale with earth movement volume and water table depth
Computation & Rendering
- Semantic layer updates: GPU compute shaders update water-flow, water-table, buildability, and pollution layers in response to heightmap edits.[1] Avoids CPU bottleneck; enables real-time visualization of flow and flooding risk as the player grades terrain
- Mesh generation: Terrain mesh generated from heightmap grid using clockwise (CW) triangle winding (consistent across both initial mesh generation and frustum-culled rendering paths)
- Rendered via Three.js with WebGPU backend; semantic layers drive material properties (wetness, color tint for pollution, brightness for buildability)
- Materials and texturing follow procedural material subsystem
- Integrated with procedural building and road asset placement; buildings snap to buildable cells and pay grading cost if site requires cut/fill
References
- [1] McDonald, "An Efficient Data Structure for 3D Multi-Layer Terrain and Erosion Simulation" (2022): Hybrid approach coupling surface heightmap (rendering, memory efficiency) with sparse sub-surface voxels (water/erosion/cut-fill simulation) — the data structure this doc adopts
- Cities Skylines Heightmap Generator: Example of heightmap authoring workflow
- SimCity 4 Custom Terrains and USGS Data: 1025×1025 greyscale images; elevation encoding via pixel brightness
Post-Launch Features
- Terrain Dock Toolbox: Dedicated "Terrain" tab and toolbox in the HUD dock for manual terraforming (raise, lower, level, smooth, brush softness) and scenario editing. Undo/redo already works today (brush strokes push onto the generalized engine history system, same as roads and zones); the dedicated dock tab, plan sidebar, and data-view overlays remain post-launch.
- Tunnels & underpasses (Rush Hour expansion model): Implemented via sparse sub-surface voxel grid; allows roads and rapid transit to pass below terrain. Triggers new cut-and-cover construction mechanic and enables vertical city growth
- Terrain deformation UI polish — brush softness, region selection tools
- Animated Undo/Redo Morphing: Morph the heightmap between undo/redo states instead of snapping, for clearer visual feedback on what changed
- GPU-Compute Marching Squares: Offload contour extraction to GPU compute shaders for large terrain extents if CPU extraction profiles as a bottleneck
- Erosion and natural drainage simulation — complex hydrology model using water-flow layer as input
- Seasonal flooding and storm surge — animated water-level changes driven by weather system