Trinittu/proc-terrain/TERRAIN_CONTROL_SPEC.md

Terrain Control System Specification

Summary

Provide artists with deterministic, in-editor control over procedural terrain generation by introducing control layers (biomes, height profiles, masks, slope limits) and hard scene constraints (bel vedere stations and rail splines). The generator must combine these inputs to produce a terrain mesh and mask/biome outputs suitable for materials and prop placement.

Goals

• Allow artists to explicitly control biomes, height profiles, masks, and slope limits.
• Ensure rails and stations act as hard constraints that shape/flatten the terrain.
• Support a procedural rail spline (Path3D + Curve3D) with known points near stations.
• Provide real-time preview and regeneration in-editor.
• Expose data for props placement (density/exclusion by biome/slope/rail distance).

Non-Goals

• Final art-quality shader/material authoring.
• Runtime streaming or terrain LOD.
• Full track generation algorithm (assumed to exist elsewhere).

Inputs

Scene Inputs (Hard Constraints)

• Bel vedere stations: placed as scene nodes (Node3D).
• Rail spline: Path3D with Curve3D (procedural). Only points near stations are known.

Artist Inputs (Control Layers)

• Biome map (Texture2D): defines biome IDs/weights across terrain.
• Height profile (Curve): maps base noise height to final height per biome.
• Mask layers (Texture2D array): painted/assigned regions (forest, village, rock, etc.).
• Slope limit map (Texture2D): limits maximum slope per region.

Data Model

TerrainControlLayers (Resource)

• biome_map: Texture2D
• height_profile: Curve
• slope_limit_map: Texture2D
• mask_layers: Array[Texture2D]
• mask_names: Array[String]
• resolution: Vector2i (shared texture resolution for all layers)

TerrainGenerator (Node)

• control_layers: TerrainControlLayers
• station_paths: Array[NodePath]
• rail_paths: Array[NodePath]
• rail_influence_radius: float
• station_influence_radius: float
• station_flatten_height: float
• rail_flatten_strength: float
• biome_preview_mode: enum (None, Biome, Slope, MaskIndex)

Workflow

1. Artist places bel vedere station nodes in the scene.
2. Rail spline is generated as Path3D with Curve3D (known points near stations).
3. Artist assigns/creates a TerrainControlLayers resource.
4. Artist paints biome map and mask layers in-editor and sets height/slope controls.
5. TerrainGenerator regenerates and previews terrain with rail/station constraints.

Generation Pipeline

1. Base height: sample noise and scale by max_height.
2. Apply height profile: evaluate Curve to remap height.
3. Apply island/edge mask if enabled.
4. Sample biome map and masks to modulate height and material blending.
5. Apply slope limits by clamping local height gradients per pixel.
6. Apply rail constraints:
   • Compute distance from vertex to nearest point on rail spline.
   • Within rail_influence_radius, flatten height toward rail height.
   • Enforce maximum slope along rail direction.
7. Apply station constraints:
   • Within station_influence_radius, flatten to station height.
   • Optionally expand a platform/yard mask for props and paths.
8. Output: mesh + per-vertex data for materials (biome/mask indices) and props.

Rail Spline Handling

• Rail spline is Path3D with Curve3D and may be partially defined near stations.
• The generator samples the spline at fixed intervals to build a distance field.
• If only station-adjacent points exist, interpolate curve points between stations.

Editor Tooling

• Terrain Control Painter:
  • Paint biome IDs, slope limits, and masks directly on terrain.
  • Toggle view modes (biome/slope/mask overlays).
  • Provide brush size, hardness, and opacity.
• Preview toggle:
  • Regenerate terrain on parameter changes in the editor.

Props Integration

• Provide maps to props system:
  • biome_id, slope_limit, rail_distance, station_distance, mask values.
• Placement rules can use these to control density and exclusions.

Definition of Done

• Artists can paint biomes/masks and see results in-editor.
• Terrain respects rail and station constraints.
• Slope limits and height profiles affect terrain as expected.
• Outputs for props placement are available and consistent.

Open Questions

• How is rail height defined relative to terrain (absolute Y or curve metadata)?
• Should station flattening use station Y or a per-station override value?
• Expected texture resolution for control layers?