157 lines
6.1 KiB
Markdown
157 lines
6.1 KiB
Markdown
# 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_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.
|
|
}
|
|
```
|