| --- |
| 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. |
|
|
|  |
|
|
| - **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. |
|
|
