# Roblox Studio Terrain Importer & Voxel Sculpting Guide

This directory contains **31 PNG terrain maps & blueprints** (plus 5 editable SVGs and the Python heightmap generator `generate_pines_heightmap.py`) for **The House in the Pines** (`2048 × 2048 × 256` studs, 4 studs per voxel).

---

## 1. Direct Roblox Studio Import Maps (`1024 × 1024` & `512 × 512`)

Open **Roblox Studio → Terrain Editor → Create → Import** and configure:

| Parameter | Recommended Value | Notes |
| :--- | :--- | :--- |
| **Heightmap** | [`house-in-the-pines-heightmap-1024.png`](house-in-the-pines-heightmap-1024.png) | High-precision `1024 × 1024` grayscale map (or [`house-in-the-pines-heightmap-512.png`](house-in-the-pines-heightmap-512.png) for 1:1 4-stud voxel import) |
| **Colormap** | [`house-in-the-pines-colormap-1024.png`](house-in-the-pines-colormap-1024.png) | Matching `1024 × 1024` albedo tint map (`#2B3E2E` pine floor, `#6E583F` dirt trail, `#4E565E` granite cliff, `#3A4632` bog mud) |
| **Position** | `0, 0, 0` | Centers the valley at world origin |
| **Size (Studs)** | `2048, 256, 2048` | `4 studs/voxel` horizontal scale with `256 studs` (`64m`) vertical elevation range |
| **Base Material** | `LeafyGrass` | Overridden along slopes, paths, and wetlands during the Voxel Paint pass |

---

## 2. Six `1024 × 1024` Technical Splatmaps & Reference Overlays

1. **[`house-in-the-pines-heightmap-1024.png`](house-in-the-pines-heightmap-1024.png)** — Raw 1024×1024 grayscale elevation map with anti-aliased ravine stream channels, terraced building pads, and stepped north ridge cliffs (`0–255` mapped to `0–256 studs`).
2. **[`house-in-the-pines-colormap-1024.png`](house-in-the-pines-colormap-1024.png)** — Companion 1024×1024 Roblox Terrain Importer colormap for automatic surface tinting across biomes.
3. **[`house-in-the-pines-biome-mask-1024.png`](house-in-the-pines-biome-mask-1024.png)** — Color-coded 7-biome splatmap mask:
   - **RED**: `Ground` + `Mud` road & trail network (`12–16 studs` wide)
   - **GREEN**: `LeafyGrass` pine forest floor (`40–65%` canopy cover)
   - **BLUE**: `Rock` + `Slate` steep cliffs (`> 42°` slope)
   - **YELLOW**: `Grass` flattened building terraces (Cabin, Shed, Watchtower)
   - **CYAN**: `Water` + `Mud` ravine stream, pond basin, and south bog
4. **[`house-in-the-pines-water-and-excavation-mask-1024.png`](house-in-the-pines-water-and-excavation-mask-1024.png)** — Sub-surface subtraction and hydrology mask:
   - **GOLD**: Subtract `32 × 28 × 12 st` for the Cabin Cellar & Stone Stairwell (`Y = +4m to +16m`)
   - **MAGENTA**: Subtract `16 × 192 × 14 st` horizontal adit for the East Mine Tunnel (`Y = +28m`)
   - **ORANGE**: Subtract `24 × 10 × 8 st` trench for the SW Road Culvert (`Y = +5m`)
   - **CYAN**: Fill `Terrain.Water` at `Y = +6m` (South Wetland & Pond) and stepped ravine cascades
5. **[`house-in-the-pines-contour-topographic-1024.png`](house-in-the-pines-contour-topographic-1024.png)** — 1024×1024 USGS-style topographic survey with `2m` minor contours, `10m` index contours, spot elevations (`+4m` to `+58m`), and `256-stud` grid coordinates.
6. **[`house-in-the-pines-slope-and-navmesh-1024.png`](house-in-the-pines-slope-and-navmesh-1024.png)** — 1024×1024 slope angle and AI pathfinding heatmap:
   - **Emerald (`0°–15°`)**: Flat building pads & full-speed trails
   - **Lime (`15°–30°`)**: Walkable forest floor & Visitor stalking ring
   - **Amber (`30°–45°`)**: Steep scrambling banks (`0.75×` walk speed)
   - **Crimson (`> 45°`)**: Non-walkable natural cliff barrier (`MaxSlopeAngle = 42°`)

---

## 3. Fixed-Y Terrace Flattening Coordinates

After importing the heightmap, select **Terrain Editor → Edit → Flatten (Fixed Y Plane)** to create crisp foundations for modular cabin and outpost meshes:

- **Escape Gate & Washout Pad (SW)**: Flatten at `Y = +8m (32 studs)`
- **Main Cabin Clearing & Porch Pad (Center)**: Flatten `96 × 96 studs` at `Y = +16m (64 studs)`
- **Generator Workshed Bench (East of Cabin)**: Flatten `48 × 48 studs` at `Y = +18m (72 studs)`
- **East Mine Adit Shelf (NE Escarpment)**: Flatten entrance ledge at `Y = +28m (112 studs)`
- **Fire Watchtower Crown (North Peak)**: Flatten `64 × 64 studs` at `Y = +42m (168 studs)`

---

## 4. Complete 23-Sheet Terrain Engineering Blueprint Index

See [`GALLERY.md`](GALLERY.md) for full previews of all 23 visual engineering sheets (`01` through `23`), including:
- **Sheets `01`–`05`**: Concept overview, playable valley map, clean topography, asset placement, and biome zones.
- **Sheets `06`–`15`**: Voxel material palette (`06`), elevation cross-sections (`07`), natural cliff barriers (`08`), water/mud erosion (`09`), 2048-stud master world map (`10`), Visitor acoustic heatmap (`11`), underground excavation (`12`), foliage sightlines (`13`), elevation fog/reverb zones (`14`), and weather/seasonal lighting (`15`).
- **Sheets `16`–`23`**: 6-step Studio sculpting workflow (`16`), hypsometric 5m contour map with transect graph (`17`), slope & NavMesh walkability map (`18`), 4 regional 512×512 zoom blueprints (`19`–`22`), and voxel-to-mesh foundation blending (`23`).