Add shape registry

API.md

@@ -0,0 +1,95 @@
+# 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.
+
+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 

init.lua

@@ -0,0 +1,12 @@
+local modpath = minetest.get_modpath(minetest.get_current_modname())
+
+local function load(name)
+    dofile(modpath.."/lua/"..name..".lua")
+end
+
+-- Global variable that can be used by other mods
+-- Please see API.md for reference
+noordstar_caves = {}
+
+-- Load features to influence cave shapes
+load("shape")

lua/shape.lua

@@ -0,0 +1,48 @@
+-- This file takes care of the cave shapes.
+
+noordstar_caves.registered_shapes = {}
+
+-- Clean the input and return a valid shape def
+-- If the input is invalid, return nil
+local function clean_def(def)
+    if type(def.name) ~= "string" then
+        return nil
+    end
+    if type(def.connectivity_point) ~= "number" then
+        return nil
+    end
+    if type(def.verticality_point) ~= "number" then
+        return nil
+    end
+
+    local d = {
+        name = def.name,
+        connectivity_point = def.connectivity_point,
+        verticality_point = def.verticality_point
+    }
+
+    if type(def.noise_params) == "table" then
+        d.noise_params = def.noise_params
+    end
+
+    if type(def.func) == "function" then
+        d.func = def.func
+    else
+        d.func = function(pos, v) return v end
+    end
+
+    if type(def.y_min) == "number" and type(def.y_max) == "number" then
+        d.y_min = def.y_min
+        d.y_max = def.y_max
+    end
+
+    return d
+end
+
+function noordstar_caves.register_shape(def)
+    local d = clean_def(def)
+
+    if d ~= nil then
+        noordstar_caves.registered_shapes[d.name] = d
+    end
+end