# WorldEngine: generating a world from plate tectonics down to biomes

> WorldEngine is an MIT licensed Python world generator that simulates tectonic plates, precipitation with rain shadows, erosion and the Holdridge life zones model to produce elevation, temperature, precipitation, biome and ocean maps plus a binary world file. Its output is meant to be loaded by other tools.

**Mindwerks/worldengine** — World generator using simulation of plates, rain shadow, erosion, etc.

- Repository: https://github.com/Mindwerks/worldengine
- Stars: 1,078 · Forks: 135
- Language: Python
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/mindwerks-worldengine

## One command produces a world and five map images

WorldEngine is a world generator that simulates plate tectonics, rain shadows, erosion and the Holdridge life zones model, and the whole thing is driven from a command line.

The quick example is one line:

```bash
worldengine world -s 1 -n seed1
```

The subcommands are world, plates, ancient_map and info, and the full usage is worldengine [options] [world|plates|ancient_map|info].

A fuller invocation sets the seed, the output name, the number of plates and the map dimensions:

```python
worldengine -s 4 -n an_example -q 25 -x 2048 -y 2048
```

And the console output shows what each flag did, which is useful documentation in itself:

```
Worldengine - a world generator (v. 0.19.0)
-----------------------
 operation            : world generation
 seed                 : 4
 name                 : an_example
 width                : 2048
 height               : 2048
 number of plates     : 25
 world format         : protobuf
 black and white maps : False
 step                 : full
 greyscale heightmap  : False
 rivers map           : False
 scatter plot         : False
 fade borders         : True

starting (it could take a few minutes) ...

Producing ouput:
* world data saved in './an_example.world'
* ocean image generated in './an_example_ocean.png'
* precipitation image generated in './an_example_precipitation.png'
* temperature image generated in './an_example_temperature.png'
* biome image generated in './an_example_biome.png'
* elevation image generated in './an_example_elevation.png'
...done
```

Two things stand out. The warning that it could take a few minutes is real, because a full run at 2048 by 2048 with 25 plates involves erosion simulation. And the output is both a binary world file and a set of images, which is the shape that makes the tool useful to other programs rather than only to a person looking at a picture.

There is also a second command, ancient_map, which takes the generated world file and renders it in an antique cartographic style:

```bash
worldengine ancient_map -w seed1.world
```

## The generation phases are a causal chain

The algorithm section lists the phases in order, and the order is the whole point.

Plate simulation comes first, and the reason given is that it is the best way to get proper mountain chains. For this, pyplatec is used, which is a separate project of the same organisation, so the plate tectonics itself is delegated to a separate library rather than implemented here. The PyPlatec dependency is pinned to exactly version 1.4.3, which is the kind of pin that matters when a native library sits underneath.

Noise techniques are used at different steps. Then precipitation is calculated considering latitude and rain shadow effects. Then erosion is calculated. Then humidity in each zone is calculated. Then terrain permeability is calculated. And finally the biome is calculated using the Holdridge life zones model.

Read as a pipeline, this is a chain of causes. Mountains rise where plates converge, and mountains block moisture, so the far side of a range is dry, and that dry side gets a desert biome, and the wet side gets a forest, and the map is legible because the patterns follow from each other rather than from independent noise fields.

That is the substantive difference from a fractal noise generator, and it is why this project is used for simulation as well as for game maps.

The README names a specific downstream use: the created world can be used for simulating the evolution of a civilization, referring to the civs project. A world with causally consistent climate and biomes is a more reasonable starting point for a civilisation simulation than random noise, because the constraints the simulation has to respect are the ones a real map would impose.

## The world file is the product, the images are a view of it

The interoperability section is the one that decides whether WorldEngine is a tool you run once or a library you build on.

Worlds can be loaded into Python applications using WorldEngine itself as a library, and Java applications can instead use WorldEngine-Java, a separate library for loading WorldEngine files. Worlds can be saved using the protobuf format or hdf5, for which there are libraries in several languages, and the project says it keeps working on supporting more formats and is always interested in ways to improve interoperability.

So the binary world file is the primary artefact and the PNG images are a rendering of it. That is the correct priority for a world generator, because the interesting use of a generated world is usually to feed it into another program, whether that is a civilisation simulation, a strategy game, or a dataset.

The protobuf choice is also the one that pays off for the Python case specifically. A protobuf message is a self-describing, compact, language-neutral encoding, and the protobuf dependency is in the core requirements rather than an optional extra. The hdf5 path is the alternative for scientific tooling, and it is optional, which means it needs h5py and a Cython compile step.

The output images are the standard set for this kind of generator. For seed 1 you get an elevation map, a precipitation map, a temperature map, a biome map and an ocean map, all as PNGs through the pypng library, and the manual points out that there are several optional outputs and many options to control the result, including rivers maps, scatter plots, greyscale heightmaps and black and white map variants.

## Installing it with uv, pip, Docker or from source

Python 3.9 or newer is required according to the README, and the install section offers four routes, with uv recommended as fast.

The uv route installs uv itself, creates a virtual environment and installs the package in editable mode with the extras:

```bash
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create environment and install
uv venv
uv pip install -e ".[hdf5,dev]"
```

The pip route has a caveat worth reading:

```bash
# Currently not yet released on pypi, you may want to still use Lands or WorldSynth
# or alternatively download the source
pip install worldengine
```

So the PyPI name is claimed, the README says the package is not yet released there, and it points you to Lands or WorldSynth as alternatives. That is a real gap for anyone who wants pip install to just work, and it is a small sign that the packaging is not where the effort goes.

The Docker route is one script after you have the source:

```bash
bin/run_in_docker.sh
```

And from source, the manual route is a venv plus an editable install:

```bash
git clone https://github.com/Mindwerks/worldengine.git
cd worldengine

# Or manual setup
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e ".[dev]"

# Run tests
pytest -v tests
```

There is also a setup_venv.sh script for a quick setup, which the README says requires pyenv, and tox for testing across all supported Python versions.

Binary packages for Windows, Linux and Mac are on the releases page, with the warning that the executable is currently out of date and that you need a copy of the worldengine src directory in the same folder as the exe.

## Packaging, the optional extras, and the toolchain

The pyproject.toml is modern and worth reading, because it documents the supported versions and the extras in one place.

The build system is setuptools with wheel, the project requires Python 3.10 or newer, and the classifiers list Python 3.10 through 3.14. The development status is listed as 4 - Beta, and the intended audience is Developers and Science/Research, with topics of Games/Entertainment Simulation and Scientific/Engineering. The licence is MIT License.

The version is dynamic and read from worldengine/version.py by setup.py, which is why the setup script executes that file to define __version__. The core dependencies are the same four: PyPlatec pinned to 1.4.3, pypng, numpy and protobuf.

The optional dependency groups are the interesting part. The hdf5 extra brings Cython 3.0 or newer and h5py 3.10 or newer, for the HDF5 world format. The gdal extra is for heightmap export in various formats, with a comment that it requires system GDAL libraries, libgdal-dev on Ubuntu and gdal on macOS via brew, and the installation commands given in the comment.

The dev extra is a full development toolchain: Cython and h5py for testing, pytest and pytest-cov for testing, ruff and mypy for code quality, pre-commit for hooks, sphinx and sphinx-rtd-theme for documentation, and tox for multi-version testing.

The Dockerfile is straightforward. It starts from python:3.11-slim, installs gcc, g++, libhdf5-dev and pkg-config for PyPlatec and h5py, installs the package in editable mode with the hdf5 and dev extras, and the default command is worldengine --help.

The repository layout supports all of this: pyproject.toml and setup.py at the root, a setup.cfg, a tox.ini for multi-version testing, an uv.lock, a .pre-commit-config.yaml, a Dockerfile, a biomes.scm file, and directories for the worldengine package, the tests, the docs, the manual and a bin/ directory holding the Docker script.

## Where WorldEngine is the wrong tool

The first wrong case is a game needing a lot of world quickly. A full world run takes minutes, and the generation is sequential in its phases because each depends on the previous result. If you need hundreds of tiles at interactive rates, a noise-based generator with a fast path is the right tool and this is not it. WorldEngine is for producing a world once, then consuming it.

The second is the PyPI situation. The README says the package is not yet released on PyPI, so pip install worldengine as written may not give you the current code. If your deployment pipeline depends on a package index, that is an obstacle, and the workaround of downloading source or using a Docker image is more friction than a mature project would impose.

The third is the interaction between the pieces. PyPlatec is a native library with a pinned version, hdf5 needs a Cython compile, and GDAL needs system packages installed separately. Each of those is fine on a workstation and annoying in a container image or a locked-down CI environment. The Dockerfile handles the first two, but you are assembling a native dependency chain rather than installing a self-contained wheel.

The fourth is the maintenance state, which the release history makes plain. The current stable version is 0.20.0, released on 2025-11-18, and before it sit 0.19.0 from 2016 and 0.18.0 from 2015. So there was a decade of slow development and then a jump to a modern release in late 2025, and the last push was on 2026-08-27. That is a project coming back to life rather than one with a steady release cadence, which is good news for the code and a caution for planning around version numbers.

One more thing to know: the GUI is a separate project, worldengine-gui, and it is described as experimental and limited.

## Conclusion

WorldEngine is a good pick for a research, simulation or game project that needs worlds whose mountains, deserts and forests follow a causal chain rather than a noise function, because the plate simulation and rain shadow stages are what make the biome map readable rather than random, and the protobuf world file lets another program consume the data directly; it is the wrong pick if you need a fast tile generator for a game, since a full world run takes minutes, and before you start you should decide on the output format, because protobuf is the default and the hdf5 path needs a Cython compile.

## FAQ

### How do I generate a world with WorldEngine?

Run worldengine world -s 1 -n seed1 for a basic world, or worldengine -s 4 -n an_example -q 25 -x 2048 -y 2048 to set the seed, name, number of plates and map size. The run produces a binary world file plus elevation, precipitation, temperature, biome and ocean PNG maps.

### What simulation does WorldEngine perform?

The phases are plate simulation using pyplatec, noise techniques at different steps, precipitation calculated with latitude and rain shadow effects, erosion, humidity per zone, terrain permeability, and finally the biome using the Holdridge life zones model. The mountain chains come from the plate simulation, and the rain shadows drive the dry and wet sides of them.

### In what formats can WorldEngine save a world?

Protobuf and HDF5, with libraries available in several languages. Python applications can load worlds with WorldEngine itself as a library, and Java applications use the separate WorldEngine-Java project. The protobuf format is the default and hdf5 needs the optional hdf5 extra with h5py and Cython.

### How do I install WorldEngine?

The README recommends uv, with uv venv followed by uv pip install -e ".[hdf5,dev]". There is also a Docker route via bin/run_in_docker.sh, a source route with python -m venv and pip install -e ".[dev]", and binary packages on the releases page, though the executable is described as out of date.

### Is WorldEngine on PyPI?

The README states that it is currently not yet released on PyPI, and suggests using Lands or WorldSynth or downloading the source instead. The current stable version is 0.20.0, and the project requires Python 3.9 or newer.

## Sources

- [Issues](https://github.com/Mindwerks/worldengine/issues)
- [License: MIT](https://github.com/Mindwerks/worldengine/blob/master/LICENSE)
- [Mindwerks/worldengine on GitHub](https://github.com/Mindwerks/worldengine)
- [README](https://github.com/Mindwerks/worldengine/blob/master/README.md)
- [Releases](https://github.com/Mindwerks/worldengine/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mindwerks-worldengine