Add documentation summarizing the world generation algorithm

Author: patowen

docs/README.md

@@ -32,15 +32,8 @@ This is subject to change.
     * Chunks and their coordinate systems (explaining node_to_dual and dual_to_node)
     * Voxels within chunks (Margins should be mentioned here.)
     * The graph (how dodecahedra are organized into the tiling in code. Also mention how NodeId works.)
-* World generation
-    * Introduction (explain NodeState and ChunkParams)
-    * Environmental factors (how they change from node to node)
-    * The surface (explain the flat plane of the world, and how gravity works)
-    * Terrain (explain parts of the generate_terrain function that determine void vs non-void, ignoring material for now)
-    * Materials of the terrain
-    * The road
-    * Trees
-    * How world generation is driven (wait until this section to describe anything async or anything related to margins)
+* World generation (See `world_generation.md`)
+* How world generation is driven (wait until this section to describe anything async or anything related to margins)
 * Character physics (May want to mention the word "player" for searchability)
     * The movement algorithm (generally describing character_controller/mod.rs)
     * Constraining movement vectors (describing vector_bounds.rs)

docs/world_generation.md

@@ -0,0 +1,75 @@
+# World generation
+World generation in Hypermine is constrained the following principles:
+* The generated contents of each chunk must depend only on the parameters of the world generation algorithm, not on gameplay.
+* Everything must be generated in its settled state to ensure that unmodified terrain does not need to be stored on disk, and to help with immersion.
+* World generation should be as isotropic as reasonably possible, so that it is not obvious which direction leads to the origin.
+
+These constraints help inspire the details of the world generation algorithm, which are explained further in the sections below.
+
+## Noise
+Every procedural world generation algorithm needs to start with some way of generating noise. This noise is useful for determining properties like temperature and rainfall (which affects what material the ground is made of), and it is also used in determining the shape of the terrain. While Perlin noise is often used as a standard approach, it is not clear how it would be adapted to a large hyperbolic world. Instead, Hypermine uses a different approach specifically designed for a hyperbolic tiling, inspired by Hyperrogue.
+
+### Coarse noise function output
+The first step is to form a coarse approximation of the noise function, deciding on one value for each node. To do this, we take advantage of the tiling itself. For a 2D analogy, the pentagonal tiling of the hyperbolic plane can be thought of as a set of lines dividing the hyperbolic plane instead of individual pentagons.
+
+TODO: Picture of pentagonal tiling with lines colored to distinguish them from each other
+
+Similarly, in 3D, the dodecahedral tiling can be thought of as a set of planes dividing hyperbolic space. This interpretation of the dodecahedral tiling is important for understanding how the noise function works between nodes.
+
+To decide on a noise value for each node, we break the dodecahedral tiling up into this planes. We associate each plane with a randomly chosen noise value offset, such that crossing a specific plane in one direction increases or decreases the noise value by a specific amount, and crossing the same plane from the other side has the opposite effect. Once we decide on a noise value for the root node, this definition fully determines the noise value of every other node.
+
+The following diagram shows an example of the 2D equivalent of this algorithm.
+
+TODO: Picture of pentagonal tiling with each line labeled with the noise value offset, using arrows or something similar to show how this offset applies. The center of each pentagon is also labeled with a number with its current noise value. Integers are used everywhere to allow the reader to verify the math easily in their head.
+
+In this diagram, the randomly-chosen noise value offset of each line, along with the derived noise value of each node, is shown. Note how the difference in noise values between any two adjacent nodes matches the noise value offset of the line dividing them.
+
+This algorithm allows for random variation while keeping nearby nodes similar to each other, which is what we need from a noise function. One notable quirk worth mentioning is that the noise value is unbounded, which currently means that hills and valleys in Hypermine can become arbitrarily high and deep, respectively.
+
+### Fine noise function output
+The next step is to use this coarse approximation of the noise function to produce the actual noise function. To begin, set the noise value at the center of each node to the coarse output we computed earlier.
+
+TODO: Picture of pentagonal tiling with a color at the center of each node to represent the noise value.
+
+Then, trilinearly interpolate these values based on voxel coordinates to create a continuous function across the world. Note that in 2D, this would be bilinear interpolation.
+
+TODO: Picture of the same pentagonal tiling with gradients added. Decorate the center of each node with a dot to highlight the control points of the interpolation.
+
+Finally, for each voxel, add a random offset to its noise value, drawn independently from some distribution.
+
+TODO: Picture of same pentagonal tiling with the final noise value of each voxel.
+
+## Terrain shape
+Hypermine uses the 3D noise function to determine the shape of the terrain. This may seem surprising, as it is arguably simpler to use a 2D noise function instead to form a heightmap of the world. However, using 3D noise instead is a useful way of generating more interesting terrain with overhangs, and more importantly, a 2D heightmap works less well in hyperbolic space because of the way that space expands as you move away from the ground plane. The naive approach would cause hills and valleys to have significantly less detail than terrain near the ground plane.
+
+Instead, the basic algorithm is as follows: Using a 3D noise function, we determine the hypothetical elevation of the terrain at each voxel. We then subtract this elevation by the actual height of the voxel above the ground plane to determine a value (denoted `dist` in code) that can be roughly translated to "the voxel's depth relative to the terrain's surface". If this value is above zero, we are inside the terrain, and the voxel should be solid, and otherwise, it should be void. If the value is above zero but close to zero, one of the surface materials (like dirt) will be used, while if the value is far above zero, a material like stone will be used instead.
+
+Note that the above is a simplification of the actual algorithm. It is recommended to read the implementation of `worldgen::ChunkParams::generate_terrain` to understand all the details. For instance, terracing is used to add flatter terrain layers with steeper hills between them, and the strength of this terracing effect is controlled by another parameter affected by noise called `blockiness`. In addition, some measures are taken to make the terrain surface smoother than the interface between the different terrain layers.
+
+## Terrain material
+The terrain material depends entirely on the following four factors:
+* Elevation above the ground plane
+* Estimated distance below the terrain surface
+* Temperature
+* Rainfall
+
+Note that temperature and rainfall are noise functions set up for the purpose of allowing varying terrain materials. How these are used is described in detail in `terraingen.rs`, so the details are omitted here.
+
+## The road
+Currently, the only megastructure in Hypermine is a single infinite straight road. This megastructure works by using the state machine `worldgen::NodeStateRoad`, which is much like `worldgen::NodeStateKind`, but instead of defining the ground plane, it defines the plane that divides the road into its "east" and "west" sides (with this terminology assuming that the road runs "north" and "south"). Based on this state, the `worldgen::ChunkParams::generate_road` function will be called for chunks right above the ground plane, generating the road's surface and carving out any terrain that is in the way. The `worldgen::ChunkParams::generate_road_support` function will be called for chunks below the ground plane, generating the wooden truss if the road is above the terrain, acting as a bridge.
+
+## Trees
+For decoration, tiny two-block trees are scattered throughout the terrain, with their density depending on the amount of rainfall. Each tree is generated by placing a wood block next to a dirt or grass block, followed by placing a "leaves" block on that wood block, away from the dirt or grass block. While this algorithm is unaware of gravity, it often generates trees upright because the wood blocks are placed on relatively flat ground. See `worldgen::ChunkParams::generate_trees` for more details.
+
+Note that generating larger trees requires a more complicated algorithm that has not yet been planned out or implemented.
+
+## Implementation details
+Hypermine generates worlds in three main stages:
+* Generate a `NodeState` for each node
+* Generate a `ChunkParams` for each chunk, based on the `NodeState` of all 8 nodes adjacent to the chunk's origin
+* Using the information in `ChunkParams`, asynchronously generate the voxel data for each chunk
+
+The reasoning behind these three phases can be seen most clearly in the noise generation algorithm. The coarse noise function created at the beginning of the algorithm is stored in the `NodeState`. Since the noise needs to be interpolated between adjacent `NodeState`s, the `ChunkParams` needs all 8 adjancent nodes to be constructed. The actual interpolation and the inclusion of additional noise is done in the final, asynchronous phase of the algorithm, which depends entirely on `ChunkParams`.
+
+## Additional information
+For additional information related to world generation, it is recommended to read the code and its documentation in `worldgen.rs`, as it has many details not covered here.