This information is for version 0.2.0.
Both the full version and a demo of planetarygeneration are available on itch.io.

Early version

Please note that this is a very early version of planetarygeneration. Feel free to report any bugs you might encounter or to request features.

Demo Version

Note that the demo works just like the full version and all documentation is valid for it as well.
The only difference is that the executable is called planetarygenerationdemo instead of planetarygeneration and that the demo can’t export any results.

Changelog

0.1.0 -> 0.2.0

--config parameter is now optional, using cfg.toml as default
Seeds for the random number generators can now be defined in the configuration file
If not set, they are now random and will be printed to the console, so you can reproduce them
Better error messages in case the configuration file is invalid
Rename lift to edge_lift in configuration
Rename falloff to edge_falloff in configuration
Rename max_iter to max_iterations in configuration
Windows version is now 64Bit
Improved error messages in case the configuration file is invalid
Parameter ranges are now enforced with proper error messages
Render window now always closes properly

Configuration and usage

Subdivisions

The subdivisions cause every face of the sphere’s mesh to be divided into 4 smaller ones.
This way the quality of the generation can be improved.
The counts are accumulative, so if you once set it to 2 then on the next step to 4, you’ll end up with a 6 times subdivided mesh.

Memory Usage

Be careful when using the subdivisions settings, since every count will increase the face count by factor 4, which will also use about 4 times as much memory.
If you set this value too high, you might end up using all the memory of your machine, possibly crashing it.
The current default configuration will consume over 3GB of memory. Decrement one of the subdivisions values to drop it to around 800-900MB.

Order of execution

Below you see the execution order of the separate steps. (assuming you have all enabled)

+-------+    +---------+    +-----------+    +---------+
| Noise | -> | Meteors | -> | Tectonics | -> | Erosion |
+-------+    +---------+    +-----------+    +---------+

Configuration

The configuration file is read once on startup. If you made any changes to it, you’ll have to restart planetarygeneration.
Please keep in mind that the sphere’s size is approximately 1 when you configure settings that affect size.

General

num_cores_reserved

Number of virtual cores that shall not be used for algorithms. Since planetarygeneration is multi-threaded it might use all your CPU time, causing other programs to become unresponsive.
The setting is optional. If missing, all cores might be used. Set this value to >= 1 if you want to use your computer while planetarygeneration is running.
Set it to 0 or remove it if you want planetarygeneration to run as quickly as possible.
Note that this also competes with the rendering, so if you want it to be interactive, you should choose a value >= 1. [int >= 0]

num_cores_reserved = 2

rendering

Use the settings here to enable and configure rendering of the generation progress.
The rendering is especially helpful when you’re tuning your configuration.

[rendering]

enabled

Set to true or false to toggle the rendering. [bool]

enabled = true

width

Use this to set the initial window size. Note that it can be resized as well. [int >= 0]

width = 500

height

Use this to set the initial window size. Note that it can be resized as well. [int >= 0]

height = 400

path_vertex_shader

In case you want to use your own shader, feel free to change this to a different path.
Make sure that you don’t change the input / output parameters. [file path]

path_vertex_shader = "shaders/shader.vert"

path_fragment_shader

In case you want to use your own shader, feel free to change this to a different path.
Make sure that you don’t change the input / output parameters. [file path]

path_fragment_shader = "shaders/shader.frag"

noise_generation

These settings are used to enable and configure the initial noise generation.

[noise_generation]

enabled

Set to true or false to toggle the noise generation. [bool]

enabled = true

subdivisions

Set the number of subdivisions of the sphere’s mesh before running the noise generation. [int >= 0]

subdivisions = 2

seed

The seed to be used for the random number generator. This value is optional and a random seed will be chosen if not present. [int >= 0]

seed = 777

amp

Amplitude of the noise. Use this value to increase / decrease the effect of the noise. [float > 0]

amp = 0.3

wx

The frequency or scale of the noise pattern in the x direction. [float > 0]

wx = 1.0

wy

The frequency or scale of the noise pattern in the y direction. [float > 0]

wy = 0.9

wz

The frequency or scale of the noise pattern in the z direction. [float > 0]

wz = 0.7

octaves

Define the octaves you want to use for the noise generator as array of ints.
Please note that the factors array must have the same length.

octaves = [3, 5, 7]

factors

Define the amplitude factors of the octaves you defined.
Please note that the octaves array must have the same length.

factors = [0.1, 0.05, 0.005]

save

If you want to save the result of the noise generation, define a path here.
It will be stored as binary ply file. [file path]
The value is optional, you can comment it out if you don’t want to save the result:

# save = "foo.ply"

meteor_craters

These settings are used to enable and configure the generation of meteor impact craters.

[meteor_craters]

enabled

Set to true or false to toggle the meteor crater generation. [bool]

enabled = false

subdivisions

Set the number of subdivisions of the sphere’s mesh before running the meteor crater generation. [int >= 0]

subdivisions = 1

seed

The seed to be used for the random number generator. This value is optional and a random seed will be chosen if not present. [int >= 0]

seed = 777

n_craters

The maximum number of meteor craters that should be generated. [int >= 0]

n_craters = 50

radius_min

The minimum horizontal radius / size of a crater. (Value per crater is chosen between min and max) [float >= 0 && <= radius_max]

radius_min = 0.001

radius_max

The maximum horizontal radius / size of a crater. (Value per crater is chosen between min and max) [float >= 0 && >= radius_min]

radius_max = 0.15

depth_per_radius_min

The minimum depth of a crater depending on its radius. (Value per crater is chosen between min and max and affected by radius) [float >= 0 && <= depth_per_radius_max]

depth_per_radius_min = 0.2

depth_per_radius_max

The maximum depth of a crater depending on its radius. (Value per crater is chosen between min and max and affected by radius) [float >= 0 && >= depth_per_radius_min]

depth_per_radius_max = 0.3

save

If you want to save the result of the meteor crater generation, define a path here.
It will be stored as binary ply file. [file path]
The value is optional, you can comment it out if you don’t want to save the result:

# save = "foo.ply"

tectonics

These settings are used to enable and configure the simulation of tectonic plates / edges.

[tectonics]

enabled

Set to true or false to toggle the tectonic plates generation. [bool]

enabled = false

subdivisions

Set the number of subdivisions of the sphere’s mesh before running the tectonic plates generation. [int >= 0]

subdivisions = 0

seed

The seed to be used for the random number generator. This value is optional and a random seed will be chosen if not present. [int >= 0]

seed = 777

n_plates

The maximum number of tectonic plates to be generated. [int >= 0]

n_plates = 15

max_iterations

The maximum number of iterations / width of the edge effect when calculating the falloff from collision edges.
Bigger values yield nicer results, but might cost a lot of time. [int >= 0]

max_iterations = 100

edge_lift

The maximum lift of an edge between two tectonic plates. [float]

edge_lift = 0.09

edge_falloff

How the height changes per face distance from the collision edge of plates. [float]

edge_falloff = 0.96

height = edge_falloff * previous_height

whole_plate_lift_min

The minimum vertical lift of a tectonic plate. (Value per plate is chosen between min and max, can be negative) [float <= whole_plate_lift_max]

whole_plate_lift_min = -0.01

whole_plate_lift_max

The maximum vertical lift of a tectonic plate. (Value per plate is chosen between min and max, can be negative) [float >= whole_plate_lift_min]

whole_plate_lift_max = 0.05

amp

Amplitude of the noise applied to collision edges. Use this value to increase / decrease the effect of the noise. [float > 0]

amp = 0.3

wx

The frequency or scale of the noise pattern applied to collision edges in the x direction. [float > 0]

wx = 1.0

wy

The frequency or scale of the noise pattern applied to collision edges in the y direction. [float > 0]

wy = 0.9

wz

The frequency or scale of the noise pattern applied to collision edges in the z direction. [float > 0]

wz = 0.7

octaves

Define the octaves you want to use for the noise generator applied to collision edges as array of ints.
Please note that the factors array must have the same length.

octaves = [3, 5, 7]

factors

Define the amplitude factors of the octaves you defined.
Please note that the octaves array must have the same length.

factors = [0.1, 0.05, 0.005]

save

If you want to save the result of the tectonic plate generation, define a path here.
It will be stored as binary ply file. [file path]
The value is optional, you can comment it out if you don’t want to save the result:

# save = "foo.ply"

erosion

These settings are used to enable and configure the simulation of hydraulic erosion.

[erosion]

enabled

Set to true or false to toggle the erosion simulation. [bool]

enabled = false

seed

The seed to be used for the random number generator. This value is optional and a random seed will be chosen if not present. [int >= 0]

seed = 777

water_start

The initial amount of water dropped every iteration.
This directly affects the strength of the erosion. [float > 0]

water_start = 15.0

iterations_per_subdivision

With this setting you can both define the subdivisions and number of iterations of the erosion.
Each value defines the number of iterations, while between the values a subdivision is applied.
Please note the comments about subdivisions and their memory consumption.

iterations_per_subdivision = [10, 20, 40]

[10, 20, 40]
 ^   ^   ^
 |   |   +-- After the 30 (10+20) iterations, subdivide again and run 40
 |   |
 |   +-- After the 10 iterations, subdivide once and run 20 more iterations
 |
 +-- Run 10 iterations

water_change_per_subdivision

You can alter the dropped water amount with every subdivision.
Every subdivision the dropped water amount gets changed by this factor. [float > 0]

water_change_per_subdivision = 0.5

water = water_change_per_subdivision * water_previous_subdivision

soil_eroded_per_water

How much soil is picked up per amount of water.
Directly affects the strength of the erosion. [float > 0]

soil_eroded_per_water = 3.0

soil_capacity_per_water

To avoid water carrying too much soil, this value defines how much soil can be carried per water.
It makes sense to choose a value greater than soil_eroded_per_water. [float > 0]

soil_capacity_per_water = 9.0

max_depth

The maximum depth / iterations of a single water droplet. This setting can be used to avoid very long running simulations similar to water_amount_min. [int >= 0 <= 255]

max_depth = 120

water_amount_min

Since the simulation is long running, it makes little sense to keep simulating where there is very little water left.
With this value you can avoid wasting time, by aborting once a certain threshold water amount is reached. [float >= 0]

water_amount_min = 0.0003

scale_factor

This factor defines what “size” the soil change shall have. Please note that the initial sphere has a size of 1. [float > 0]

scale_factor = 0.00003

effect_on_sphere = scale_factor * soil

water_change_factor

How the water amount shall change every iteration. [float > 0]

water_change_factor = 0.95

water = water_change_factor * water_previous_iteration

steep_pow

This affects the erosion’s strength depending on the steepness of slopes.
Use this to generally affect the steepness of slopes. [float > 0]

steep_pow = 2.0

eroded = OTHER_FACTORS * steepness^steep_pow

save_every and save_every_path

Since the erosion step might run a long time and it’s not clear how many iterations you should run to yield a good result, you can also save intermediate results as binary ply. [int >= 0 / file path]
Both these values are optional, but have to be enabled / disabled together.

save_every = 10
save_every_path = "intermediate.ply"

Saves the erosion’s result every 10 iterations to intermediate.ply.

save

If you want to save the result of the erosion simulation, define a path here.
It will be stored as binary ply file. [file path]
The value is optional, you can comment it out if you don’t want to save the result:

# save = "foo.ply"

Controls

If you have rendering enabled, you can use the following controls:

Move camera
  [W] [A] [S] [D] [SPACE] [CTRL] [C]

Rotate camera
  [Q] [E] [ARROW KEYS]

Change camera speed
  [MOUSE WHEEL]

Close
  [ESC]

Using / Running planetarygeneration

Once you created a configuration file as described under Configuration, you can start running planetarygeneration from a console window (e.g. cmd.exe or powershell.exe on Windows).
If you’re using the demo replace planetarygeneration with planetarygenerationdemo below.

If you want to run planetarygeneration with the default configuration file cfg.toml use:

planetarygeneration

To use another configuration file, pass its path as --config parameter:

planetarygeneration --config "MyConfiguration.toml"

In case you break your configuration file, you can use --generate-config to create a new one:

planetarygeneration --generate-config "NewCfg.toml"

With the --help parameter you can print additional information:

planetarygeneration --help