Make some test with terrain generator

proc-terrain/TERRAIN_CONTROL_SPEC.md

@@ -0,0 +1,100 @@
+# 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?