noordstar_caves/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:

{
    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