Terrain Generator API

# Terrain Generator API

Generate procedural terrain heightmaps for s&box. Returns .r16 (raw 16-bit) or PNG format.

> **Queue API**: For queue position tracking and estimated wait times, use the [unified Queue API](/wiki/tools-api/queue-api) with `tool=terrain`.

## Endpoint

```
POST /api/tools/terrain
```

## Parameters

Send as `multipart/form-data` or `application/x-www-form-urlencoded`. No file upload needed.

| Field | Required | Description |
|---|---|---|
| `resolution` | No | Heightmap resolution. 64 - 4096, default 512 |
| `seed` | No | Random seed integer. Default: random. Same seed = same terrain. |
| `hills` | No | Number of hills. 0 - 50, default 6 |
| `ridges` | No | Number of mountain ridges. 0 - 20, default 1 |
| `craters` | No | Number of craters. 0 - 20, default 0 |
| `plateaus` | No | Number of flat-topped plateaus. 0 - 20, default 0 |
| `valleys` | No | Number of valleys. 0 - 20, default 0 |
| `waterLevel` | No | Minimum height floor. 0 - 1.0, default 0 |
| `island` | No | `true` to apply island falloff (edges taper to zero). Default: false |
| `format` | No | `r16` (default) or `png` |

## Response

```json
{
  "ok": true,
  "downloadUrl": "/uploads/temp/123/terrain_1024.r16",
  "resolution": 1024,
  "seed": 42,
  "format": "r16"
}
```

## Output Formats

- **`.r16`** -- Raw 16-bit big-endian heightmap. This is what s&box's terrain system imports directly. Each pixel is 2 bytes, resolution x resolution pixels.
- **`.png`** -- 8-bit grayscale PNG. Lower precision but viewable in any image editor.

## Terrain Features

The generator places random features based on the seed:

- **Hills** -- Smooth gaussian mounds with cosine falloff
- **Ridges** -- Linear mountain ranges with sinusoidal profile
- **Craters** -- Bowl-shaped depressions with raised rims
- **Plateaus** -- Flat-topped elevated areas with cliff edges
- **Valleys** -- Linear depressions cut into the terrain

All features are normalized to 0-1 range after generation.

## Deterministic Generation

Using the same `seed` value always produces identical terrain. This is useful for:
- Reproducible builds in CI/CD pipelines
- Generating matching terrain across team members
- Batch-generating variants by incrementing the seed

## Example: cURL

```bash
# Generate terrain
curl -X POST https://api.sboxcool.com/tools/terrain \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "resolution=1024" \
  -F "hills=8" \
  -F "ridges=2" \
  -F "island=true" \
  -F "seed=42"

# Download (use downloadUrl from response)
curl -o terrain.r16 https://sboxcool.com/uploads/temp/123/terrain_1024.r16
```

## Example: Python

```python
import requests

resp = requests.post("https://api.sboxcool.com/tools/terrain",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    data={"resolution": 1024, "hills": 8, "ridges": 2,
          "island": "true", "seed": 42})

data = resp.json()
r16 = requests.get(f"https://sboxcool.com{data['downloadUrl']}")
with open("terrain.r16", "wb") as f:
    f.write(r16.content)
```

## Example: Batch Generation

```bash
# Generate 10 terrain variants
for i in $(seq 1 10); do
  RESP=$(curl -s -X POST https://api.sboxcool.com/tools/terrain \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "resolution=512" -F "hills=6" -F "seed=$i")
  URL=$(echo $RESP | jq -r '.downloadUrl')
  curl -o "terrain_$i.r16" "https://sboxcool.com$URL"
done
```