
How to create a new world map

[[_TOC_]]

## The Basics

You'll need the following tools:

1. a text editor

We'll assume:

1. your new world is named WORLD

You'll have to edit files at:

```sh
voxelgarden/
└── saves/
    └── WORLD/
        └── map.mpk.gz
```

NOTE: Instead of the `voxelgarden` application, world maps are generated with
the `terraform` application. Right now, this is a pretty experimental and
glitchy program; there are many inputs that can crash it.

### Generating Config File

To generate a map config file run `terraform` with the `-c` option:

```sh
voxelgarden-terraform -c WORLD.cfg
```

### Editing Config File 

Then you can edit `WORLD.cfg` with a text editor. It will look like this:

```ini
[heightmap]
size = 512
seed = 0
height = 32
noise = 96

[drop]
drops_per_chunk = 32
max_iterations = 80
deposition_rate = 0.06
erosion_rate = 0.08
iteration_scale = 0.04
friction = 0.7
speed = 10.0
radius = 0.8
```

The heightmap section has arguments to build the original shape:

| field             | explanation       |
|-------------------|-------------------|
| size    | size of the world in pages/chunks |
| seed    | seed for randomness |
| height   | maximum height of the basic land shape |
| noise | additional height of the noise |

Notes:

1. total maximum land height is `height + noise`.
2. higher noise values will adjust the land slope to ensure that there are no
   islands in the world border.

The drop section has arguments to simulate erosion

| field             | explanation       |
|-------------------|-------------------|
| drops_per_chunk   | how many drops will be simulated in each point for erosion |
| max_iterations    | how many steps will be simulated per drop before giving up |
| deposition_rate   | amount of sediment carried by the drop that is left behind per step |
| erosion_rate      | amount of that the drop scrapes per step |
| iteration_scale   | how the drop grows as it grows old |
| friction          | how much the drop speed falls each step |
| speed             | how much speed the drop gains each step |
| radius            | randomness applied to the drop position |

### Generating Map

Once the file has been edited, you can run again the `terraform` tool

```sh
voxelgarden-terraform WORLD.cfg
```

This will take some time; a progress bar will be shown in the shell while it
runs. At the end you will have two files:

* `map.png` contains a human-readable image of the generated map. This is
  merely a visualization aid and it's not required by the program
* `map.mpk.gz` contains the computer-readable world maps

### Placing the Map File

The `map.mpk.gz` file should be placed at `../voxelgarden/saves/WORLD/`.

Note that if you have never launched this world before, the directory will not
exist.

Note also that if you add a file to a world that was using a different map
(either the default one or a different one you made before) existing chunks
will not be regenerated.



