Add initial Decoration support, many misc. improvements & modifications

1 files changed, 48 insertions, 1 deletions

diff --git a/doc/lua_api.txt b/doc/lua_api.txt
index 93e2d5c9f..b6981582e 100644
--- a/doc/lua_api.txt
+++ b/doc/lua_api.txt
@@ -410,6 +410,18 @@ Currently supported flags:  absheight
     Also produce this same ore between the height range of -height_max and -height_min.
     Useful for having ore in sky realms without having to duplicate ore entries.
 
+Decoration types
+-------------------
+The varying types of decorations that can be placed.
+The default value is simple, and is currently the only type supported.
+
+- simple
+    Creates a 1xHx1 column of a specified node (or a random node from a list, if a decoration
+    list is specified).  Can specify a certain node it must spawn next to, such as water or lava,
+    for example.  Can also generate a decoration of random height between a specified lower and
+    upper bound.  This type of decoration is intended for placement of grass, flowers, cacti,
+    papyrus, and so on.
+
 HUD element types
 -------------------
 The position field is used for all element types.
@@ -946,6 +958,7 @@ minetest.register_craftitem(name, item definition)
 minetest.register_alias(name, convert_to)
 minetest.register_craft(recipe)
 minetest.register_ore(ore definition)
+minetest.register_decoration(decoration definition)
 
 Global callback registration functions: (Call these only at load time)
 minetest.register_globalstep(func(dtime))
@@ -1835,7 +1848,7 @@ Recipe for register_craft (furnace fuel)
 
 Ore definition (register_ore)
 {
-    ore_type = "scatter" -- See "Ore types"
+    ore_type = "scatter", -- See "Ore types"
     ore = "default:stone_with_coal",
     wherein = "default:stone",
     clust_scarcity = 8*8*8,
@@ -1857,6 +1870,40 @@ Ore definition (register_ore)
     ^ Needed for sheet ore_type.  Omit from scatter ore_type for a uniform ore distribution
 }
 
+Decoration definition (register_decoration)
+{
+    deco_type = "simple", -- See "Decoration types"
+    place_on = "default:dirt_with_grass",
+    ^ Node that decoration can be placed on
+    divlen = 8,
+    ^ Number of divisions made in the chunk being generated
+    fill_ratio = 0.02,
+    ^ Ratio of the area to be uniformly filled by the decoration.
+    ^ Used only if noise_params is not specified.
+    noise_params = {offset=0, scale=.45, spread={x=100, y=100, z=100}, seed=354, octaves=3, persist=0.7},
+    ^ NoiseParams structure describing the perlin noise used for decoration distribution.
+    ^ The result of this is multiplied by the 2d area of the division being decorated.
+    biomes = {"Oceanside", "Hills", "Plains"},
+    ^ List of biomes in which this decoration occurs.  Occurs in all biomes if this is omitted,
+    ^ and ignored if the Mapgen being used does not support biomes.
+
+    ----- Simple-type parameters
+    decoration = "default:grass",
+    ^ The node name used as the decoration.
+    ^ If instead a list of strings, a randomly selected node from the list is placed as the decoration.
+    height = 1,
+    ^ Number of nodes high the decoration is made.
+    ^ If height_max is not 0, this is the lower bound of the randomly selected height.
+    height_max = 0,
+    ^ Number of nodes the decoration can be at maximum.
+    ^ If absent, the parameter 'height' is used as a constant.
+    spawn_by = "default:water",
+    ^ Node that the decoration only spawns next to, in a 1-node square radius.
+    num_spawn_by = 1,
+    ^ Number of spawn_by nodes that must be surrounding the decoration position to occur.
+    ^ If absent or -1, decorations occur next to any nodes.
+}
+
 Chatcommand definition (register_chatcommand)
 {
     params = "<name> <privilege>", -- short parameter description