Added experimental settings to allow for a humidity perlin layer

and to allow the spawned object to *replace* the node it would otherwise
spawn on top of.

Also, extended API to allow for a node to be directly named in the
register_generate_plant() call.

API.txt

@@ -200,6 +200,13 @@ plants_lib: spawn_on_surfaces({
 				-- coldness).
 	temp_max = num,		-- Maximum temperature/lower end of the Perlin
 				-- range.  Defaults to -1 (unlimited heat).
+	humidity_min = num,	-- Minimum humidity for the plant to spawn in.
+				-- Like the temperature map, this is a Perlin
+				-- value where lower numbers mean more
+				-- humidity in the area.  Defaults to +1 (0%
+				-- relative humidity).
+	humidity_max = num,	-- Maximum humidity for the plant to spawn at.
+				-- Defaults to -1 (100% humidity).
 	spawn_on_side = bool,	-- Set this to true to spawn the node on one
 				-- side of the target node rather than the
 				-- top.  The code will search for an airspace
@@ -221,6 +228,10 @@ plants_lib: spawn_on_surfaces({
 				-- facedir function above, the values given to
 				-- the facedir parameter are for regular
 				-- nodes, not wallmounted.
+	spawn_replace_node = bool -- If set to true, the target node itself is
+				-- replaced by the spawned object.  Overrides
+				-- the spawn_on_bottom and spawn_on_side
+				-- settings.
 })
 
 By default, if a biome node, size, and count are not defined, the biome
@@ -233,45 +244,49 @@ this function with two parameters:  a table with the biome information, and
 a string or table describing what to execute if the engine finds a suitable
 node (see below):
 
-plantslib:register_generate_plant(biome, function_or_treedef)
+plantslib:register_generate_plant(biome, node_or_function_or_treedef)
 
 Where "biome" is a table containing about a dozen variables.
 
 biome = {
-	surface = "string",	-- [*] what nodes to spawn on.
+	surface = "string",	-- [*] what node to spawn on.
 	avoid_nodes = {table},	-- [*] what nodes to avoid when spawning.
 	avoid_radius = num,	-- [*] how much distance to leave between
-				       the object to be added and the objects
-				       to be avoided.
-	rarity = num,		-- how rare should this tree be in its biome?
-				   Larger values more rare, determined by
-				   math.random(1,100) > this
+				--     the object to be added and the objects
+				--     to be avoided.  If this or the 
+				--     avoid_nodes value is nil or omitted,
+				--     this check is skipped.  Avoid using 
+				--     excessively large radii.
+	rarity = num,		-- how rare should this object be in its
+				-- biome? Larger values make objects more
+				-- rare, determined by
+				-- math.random(1,100) > this
 	seed_diff = num,	-- perlin seed-diff value.  Defaults to 0, 
-				   which causes the function to inherit the
-				   global value of 329.
+				-- which causes the function to inherit the
+				-- global value of 329.
 	neighbors = {table},	-- What ground nodes must be right next to and
-				   at the same elevation as the node to be
-				   spawned on.  Defaults to the value of the
-				   "surface" string.
+				-- at the same elevation as the node to be
+				-- spawned on.  Defaults to the value of the
+				-- "surface" string.
 	ncount = num,		-- at least this many of the above nodes must
-				   be next to the node to spawn on.  Any value
-				   greater than 8 will probably cause the code
-				   to never spawn anything.  Defaults to 0.
+				-- be next to the node to spawn on.  Any value
+				-- greater than 8 will probably cause the code
+				-- to never spawn anything.  Defaults to 0.
 	depth = num,		-- how deep/thick of a layer the spawned-on
-				   node must be.  Typically used for water.
-				   Defaults to unlimited.
+				-- node must be.  Typically used for water.
+				-- Defaults to unlimited.
 	min_elevation = num,	-- minimum elevation in meters/nodes.
-				   Defaults to -31000 (unlimited).
+				-- Defaults to -31000 (unlimited).
 	max_elevation = num,	-- maximum elevation.  Defaults to +31000
-				   (unlimited).
+				-- (unlimited).
 	near_nodes = {table},	-- what nodes must be in the general vicinity
-				   of the object being spawned.
+				-- of the object being spawned.
 	near_nodes_size = num,	-- how wide of a search area to look for 
-				   the nodes in that list.
+				-- the nodes in that list.
 	near_nodes_vertical = num, -- How high/low of an area to search from
 				-- the target node.
 	near_nodes_count = num,	-- at least this many of those nodes must be
-				   in the area.
+				-- in the area.
 	plantlife_limit = num,	-- The value compared against the generic
 				-- "plants can grow here" Perlin noise layer.
 				-- Smaller numbers result in more abundant
@@ -279,10 +294,10 @@ biome = {
 				-- the range of about 0 to 0.5 being most
 				-- useful.  Defaults to 0.1.
 	temp_min = num,		-- coldest allowable temperature for a plant
-				   to spawn (that is, the highest Perlin
-				   temperature map value).
+				-- to spawn (that is, the highest Perlin
+				-- temperature map value).
 	temp_max = num,		-- warmest allowable temperature to spawn a
-				   plant (lowest Perlin temperature value).
+				-- plant (lowest Perlin temperature value).
 	verticals_list = {table}, -- Same as with the spawn_on_surfaces
 				-- function.
 }
@@ -291,15 +306,21 @@ biome = {
     is optional.  Unless explicitly stated, all unused/unsupplied parameters
     default to nil and will not affect the results of the code.
 
-Regarding function_or_treedef, this must either be a string indicating the
-name of the function that should be called if a suitable spawn location has
-been found, OR a table with an L-Systems tree definition.
+Regarding node_or_function_or_treedef, this must either be table with an 
+L-Systems tree definition, or a string with a node or function name.
 
-If you specify a string with a function name, that function will be passed a
-single position parameter (in the usual table format), indicating where the
-object should be placed.  If you specified an L-Systems tree definition, then
-that definition will be passed directly to the spawn_tree() function along
-with the position to spawn the tree on.
+If you specified a string, the code will attempt to determine, as needed, 
+whether that string specifies a node name.  If it does, that node will be
+placed on top of the target position directly.
+
+If it wasn't a node, the code will assume you meant to specify a function
+name, in which case  that function will be passed a single position parameter
+(in the usual table format), indicating where the named function should place
+the object.
+
+If you specified a table, the code assumed this table contains an L-Systems
+tree definition, then that definition will be passed directly to the
+spawn_tree() function along with the position to spawn the tree on.
 
 -----
 
@@ -312,7 +333,6 @@ grow_plants({list of options})
 These are defined like so:
 
 plants_lib:grow_plants({
-
 	grow_plant = "string",	-- Name of the node to be grown into something
 				-- else.  This value is passed to the ABM as
 				-- the "nodenames" parameter, so it is the
@@ -508,3 +528,15 @@ common temperatures on both the Centigrade and Fahrenheit scales.  Note that
 unless you're trying to model the Moon or perhaps Mercury in your mods/maps, 
 you probably won't need to bother with Perlin values of less than -0.56 or so.
 
+================
+Humidity Mapping
+================
+
+Like the temperature map above, Perlin values can be tested to determine the
+approximate humidity of the *air* in the area.  This does not check for nearby
+water, just general humidity.
+
+A value of -1 equates to 100% humidity (basically, it should be a thick fog
+if it could be seen),  a value of 0 is 50%, and a value of +1 is 0% (dry as a
+bone).
+