---
license: apache-2.0
tags:
- diffusion
- terrain-generation
- heightmap
- procedural-generation
- gamedev
- pytorch
- onnx
- webgpu
---

# Talus

Talus generates terrain heightmaps for games. You pick a terrain type and any of five measurable
properties (mean elevation, relief, slope, water coverage, roughness), and Talus draws a 64x64 map
covering 4 x 4 km with heights up to 1,200 m. It is a 23M-parameter conditional diffusion model trained
from scratch on 45,000 maps from our own procedural generator. It runs on an 8 GB consumer GPU, and on a
CPU if you can wait a few seconds per map.

![Talus-3 samples: six maps per terrain type](images/talus-3_samples.png)

- **Try it in your browser:** [talus.tersa.tech](https://talus.tersa.tech/). The model runs on WebGPU
  (or the CPU) and exports PNG, Unity RAW and OBJ.
- **Code, training and benchmarks:** [github.com/osfv/talus](https://github.com/osfv/talus)

**Talus-3** is the default model. **Talus-3.1** is a variant for flatter maps: better plains, islands
and mesas, worse ridges and mountains.

## Files

| File | Size | Contents |
|---|---|---|
| `talus-3.pt` | 93 MB | Talus-3 (default): EMA weights, configs and dataset statistics. No optimizer state. |
| `talus-3.1.pt` | 93 MB | Talus-3.1 (flat-terrain variant), same format. |
| `onnx/talus-3.onnx` | 93 MB | Talus-3 denoiser exported to ONNX (fp32). |
| `onnx/talus-3.fp16.onnx` | 47 MB | The same network with fp16-stored weights. The browser demo uses this one. |
| `onnx/talus-3.json` | 25 KB | Sampler metadata for the ONNX files: world scale, conditioning statistics, noise schedule and sampling preset. |
| `onnx/talus-3.prior.bin` | 252 KB | Placement bank the sampler uses when you leave mean elevation or relief open. |
| `SHA256SUMS.txt` | | Checksums. They match the GitHub releases. |

The `.pt` files load with `torch.load(weights_only=True)`. Sampling needs the `nullscape` package from
the GitHub repo, which holds the model code and the sampler.

## Quick start

You need Python 3.11+ and PyTorch 2.7+. RTX 50-series cards need a CUDA 12.8 build of PyTorch.

```bash
git clone https://github.com/osfv/talus
cd talus
pip install torch --index-url https://download.pytorch.org/whl/cu128
pip install -e . huggingface_hub
hf download osfv/talus talus-3.pt --local-dir checkpoints
```

Generate 16 island maps with 60% water and export them for Unity, Unreal or Godot:

```bash
nullscape sample --checkpoint talus-3 --archetype islands --prop water_fraction=0.6 \
    --n 16 --formats png16,r16,obj --unity --out exports/islands
```

Add `--device cpu` if you have no CUDA GPU. For the flat-terrain variant, download `talus-3.1.pt` the
same way and use `--checkpoint talus-3.1`.

## Which model

| You are making | Use |
|---|---|
| A mix of terrain, or ridges, hills and mountains | **Talus-3** |
| Plains, islands and coasts, or mesas and plateaus | **Talus-3.1** |

## Results

Scores on the held-out TEST split, 1,000 maps per half. Each score runs from 0 to 100, where 100 means
indistinguishable from real procedural terrain at this sample size.

| Benchmark | What it measures | Talus-1 | Talus-2 | **Talus-3** | Talus-3.1 |
|---|---|---|---|---|---|
| Realism | 25 terrain metrics vs real maps | 34.4 | 56.5 | **66.2** | 64.5 |
| Spectrum | detail at every scale (power spectrum) | 3.6 | 7.6 | 11.0 | **11.3** |
| Heights | elevation distribution | 88.5 | 98.3 | **99.1** | 98.3 |
| Slopes | slope distribution | 41.2 | 56.4 | **60.5** | 59.0 |
| Control | requested vs measured properties | 81.8 | 90.4 | 92.1 | **92.4** |
| Playability | walkable-route pass rate vs real maps | 98.4 | 97.6 | **99.9** | 99.3 |
| Diversity | variety vs real maps | **96.9** | 94.4 | 95.0 | 94.6 |
| Originality | distance from the training maps | **100** | 98.1 | 99.1 | 98.4 |
| Clean detail | no excess micro-bumps | 58.4 | 97.7 | 99.4 | **99.5** |
| **Average** | | 67.0 | 77.5 | **80.3** | 79.7 |

Per-type realism on TEST (distance to real maps over the noise floor, lower is better):

| | plains | islands | mesas | hills | mountains | ridges |
|---|---|---|---|---|---|---|
| Talus-3 | 1.17 | 1.21 | 1.43 | **1.16** | **1.71** | **1.80** |
| Talus-3.1 | **1.13** | **1.16** | **1.33** | 1.20 | 1.75 | 1.93 |

Both sample about 5.6 to 5.8 maps/s at batch 128 on an RTX 5060 (8 GB), or one map in 1.3 s. Full
scorecards and the benchmark protocol are in the [GitHub repo](https://github.com/osfv/talus/tree/master/docs).

## How it works

- **Data.** A procedural generator builds each map from fBm, billow or ridged multifractal noise, then
  runs stream-power erosion, hillslope diffusion and thermal erosion. The dataset has 50,000 maps, split
  45,000 / 2,500 / 2,500 into train, validation and test. Talus-3.1 continued training on 96,000 fresh
  maps from the same generator.
- **Model.** A pixel-space U-Net denoiser (v-prediction, cosine noise schedule) conditioned on the
  terrain type and the five properties. Training drops each property at random, so the model learns
  every subset, and classifier-free guidance strengthens the conditioning at sampling time.
- **Sampling.** 50 DDIM steps with quadratic spacing and guidance 2.0, stored in the checkpoint as its
  default preset.

## Limitations

- Talus only knows the procedural world it was trained on. It has never seen real elevation data.
- 64x64 cells at 64 m is coarse for close-up play. Treat the output as a base layer for detail noise or
  upscaling.
- Mountains and ridges remain the weakest types, and the power spectrum is still 9x the noise floor,
  mostly at the finest scales.
- The roughness control (`spectral_beta`) is the loosest of the five properties.

## License

Code and weights are under the Apache-2.0 license.