ns_cavegen/API.md

# Noordstar caves API

This mod is built in a way to be easy to change the underground world.
The API is written in a way to be very similar to the Minetest API.

## Shapes

Underground caves have varying shapes, and the variable
`noordstar.registered_shapes` contains all those definitions.

For shapes, the following functions are available:

- `noordstar_caves.register_shape(shape def)` Define a new cave shape
- `noordstar_caves.unregister_shape(name)` Remove a defined cave shape
- `noordstar_caves.clear_registered_shapes()` Remove all known cave shapes

The shapes are defined as follows:

```lua
{
    name = "noordstar_caves:bubbles",
    -- Unique name identifying the shape
    -- Namespacing is not required but recommended
    
    noise_params = {
        offset = 0.4,
        scale = 0.6,
        spread = { x = 100, y = 100, z = 100 },
        seed = 248039,
        octaves = 2,
        persistence = 0.6,
        lacunarity = 2.0,
        flags = "eased"
    },
    -- NoiseParams structure describing the perlin noise of the shape
    -- Values below 0 are always wall, values above 1 will always be part of a
    -- cave.
    -- Values in-between are either cave or non-cave depending on the
    -- cave size: lower values are only included in larger caves:
    --
    --     -0.25 -----  0  ---- 0.25 ----- 0.5 ----- 0.75 ----- 1 ----- 1.25
    --             ^         ^         ^          ^        ^          ^
    --             |         |         |          |        |          |
    --       always a wall   |   larger caves     |   most caves      |
    --                       |                    |                   |
    --            massive caves only       smaller caves         always cave

    func = function(pos, n)
        return 2 * n
    end,
    -- Function to edit the NoiseParams based on some operation.
    -- Keep in mind that this function will be run many, many times, so it is
    -- best to keep this function as trivial as possible.
    -- The function receives a node's position `pos` and the noise value `n`,
    -- and it is expected to return an updated noise value.
    -- If absent, the noise value is used as-is.

    y_min = -31000,
    y_max = 31000,
    -- Lower and upper limits for cave shapes.
    -- Optional. If absent, the shape is allowed at all heights.

    connectivity_point = 10,
    verticality_point = 40,
    -- Characteristic verticality and connectivity  for the cave shape.
    -- Similar to how biomes are created, these values create 'shape points' on
    -- a voronoi diagram with verticality and connectivity as axes. However,
    -- in contrast with biomes, the voronoi cells aren't strict shape borders:
    -- they slightly overlap, creating smoother changes between cave shapes.
    --
    -- Although the variables can be interpreted differently, the variables
    -- stand for the following:
    --
    --     - Verticality: high vertical caves have large gaps, massive holes
    --                      and great paths leading downwards
    --                    low vertical caves have mostly horizontal corridors
    --                      with relatively little vertical changes
    --
    --     - Connectivity: highly connected caves generally are one massive
    --                      connected cave system, where you can generally
    --                      navigate to other parts of the cave without breaking
    --                      blocks
    --                     lowly connected caves are usually very separate
    --                      pieces, single domes, bubbles or standard shapes
    --
    --
    -- For example:
    --
    --                       |   low verticality   |   high verticality   |
    --    -------------------|---------------------|----------------------|
    --     low connectivity  | a single large dome | a deep sinkhole      |
    --    -------------------|---------------------|----------------------|
    --     high connectivity | abandoned mineshaft | spaghetti tunnels    |
    --    -------------------|---------------------|----------------------|
}
```

## Biomes

Just like the surface world, the underground world uses biomes to decorate their
caves. The cave biomes are independent of the cave shapes.

For shapes, the following functions are available:

- `noordstar_caves.register_biome(biome def)` Define a new cave biome
- `noordstar_caves.unregister_biome(name)` Remove a defined cave biome
- `noordstar_caves.clear_registered_biomes()` Remove all known cave biomes

The biomes are defined as follows:

```lua
{
    name = "noordstar_caves:tundra",
    -- Unique name identifying the biome
    -- Namespacing is not required but recommended

    node_dust = "foo:snow",
    -- Node dropped onto floor after all else is generated

    node_floor = "foo:dirt_with_snow",
    -- Node forming the floor that the player walks on

    node_wall = "foo:ice",
    -- Node forming the side walls of the cave

    node_roof = "foo:bluestone",
    -- Node forming the ceiling of the cave

    node_air = "foo:air",
    -- Nodes filling the inside of the cave. By default, this is air.
    -- You can replace it with e.g. water to make the entire cave a water cave.
    -- Keep in mind that cave biomes can blend, so it might not always look
    -- very smooth.

    node_shell = "foo:permafrost",
    depth_shell = 3,
    -- Node forming a layer around the entire cave and thickness of this layer
    -- You can make the depth as high as you want, but raising it past 16
    -- might cause hard cut-offs at chunk edges.

    y_max = -100,
    y_min = -31000,
    -- Upper and lower limits of the cave biome.
    -- Alternatively you can use xyz limits as shown below.

    max_pos = { x =  31000, y = -100, z =  31000 }
    min_pos = { x = -31000, y = -500, z = -31000 }
    -- xyz limits for biome, an alternative to using `y_min` and `y_max`.
    -- Cave biome is limited to a cuboid defined by these positions.
    -- Any x, y or z field left undefined defaults to -31000 in `min_pos` or
    -- 31000 in `max_pos`.

    heat_point = 0,
    humidity_point = 50,
    -- Characteristic temperature and humidity for the biome.
    -- Just like the Minetest Lua API for biomes, these values create
    -- 'biome points' on a voronoi diagram with heat and humidity as axes.
    -- The resulting voronoi cells determine the distribution of the biomes.
    -- Heat and humidity have an average of 50, vary mostly between 0 and 100
    -- but can exceed these values.
}
```