Added API documentation.

API.txt

@@ -0,0 +1,152 @@
+This document briefly describes the Plantlife API.
+
+=========
+Functions
+=========
+
+There are five main functions defined by this mod:
+
+spawn_on_surfaces()
+grow_plants()
+plant_valid_wall()
+is_node_loaded()
+dbg()
+
+-----
+The first of these, spawn_on_surfaces() is defined with quite a large number
+of variables:
+
+spawn_on_surfaces = function(sdelay, splant, sradius, schance, ssurface,
+		    savoid, seed_diff, lightmin, lightmax, nneighbors, ocount)
+
+sdelay:     The value passed to the ABM's interval parameter, usually in the
+	    1000-3000 range.
+splant:     The node name of the item to spawn (e.g. "flowers:flower_rose").
+	    Note that if the plant is "poisonivy:seedling", and it's next to
+	    a wall at spawn time, it automatically becomes the wall-climbing
+	    variety.  A plant will of course only be spawned if the node about
+	    to be replaced is air.
+sradius:    Don't spawn within this many nodes of the avoid items mentioned
+	    below.
+schance:    The value passed to the ABM's chance parameter, normally in the
+	    10-100 range.
+ssurface:   Table with the names of the nodes on which to spawn the plant in
+	    question, such as {"default:sand","default:dirt_with_grass"}.  It
+	    is not recommended to put "default:dirt" or "default:stone" into
+	    this table if you can do without it, as this will cause the engine
+	    to process potentially large numbers of such nodes when deciding
+	    when to execute the ABM.
+savoid:     Table with a list of groups and/or node names to avoid when
+	    spawning the plant, such as {"group:flowers","default:tree"}.
+seed_diff:  The perlin seed difference value passed to the
+	    minetest.env:get_perlin() function.  Used along with the global
+	    perlin controls below to create the "biome" in which the plants
+	    will spawn.  Usually a value of somewhere in the 10 to 100 range
+	    is good.
+lightmin:   Minimum amount of light necessary to make a plant spawn.  Defaults
+	    to zero.
+lightmax:   Maximum amount of light present to allow a plant to spawn. 
+	    Defaults to the engine's MAX_LIGHT value of 14.
+nneighbors: Table with a list of neighboring nodes, passed to the ABM as the
+	    "neighbors" parameter, indicating what needs to be next to the 
+	    node the plant is about to spawn on, such as
+	    {"default:stone","default:water_source"}.
+ocount:     There must be at least this many of the above neighbors around the
+	    node the plant is about to spawn on for it to happen.
+
+-----
+The second function, grow_plants() is defined like so:
+
+grow_plants = function(gdelay, gchance, gplant, gresult,
+	      dry_early_node, grow_nodes)
+
+gdelay:          Passed as the ABM "interval" parameter, as with spawning.
+gchance:         Passed as the ABM "chance" parameter.
+gplant:          Name of the node being grown.  This value is passed as the 
+		 only item in the table given to the ABM as the nodenames
+		 parameter, so it is the plants themselves that are the ABM
+		 trigger, rather than the ground they spawned on.  A plant
+		 will only grow if the node above it is air.
+gresult:         Name of the node into which the above should transform when 
+		 the ABM executes.
+dry_early_node:  This value is ignored except for jungle grass, where it
+		 indicates which node the grass must be on in order for it to
+		 turn from "short" to default:dry_shrub.
+grow_nodes:	 This node must be under the plant in order for it to grow at
+		 all.  Normally this should be the same as the list of 
+		 surfaces passed to the spawning ABM as the "nodenames"
+		 parameter, such as
+		 {"default:dirt_with_grass","default:sand"}.  This is so that
+		 the plant can be manually placed on something like a flower
+		 pot or something without it growing and eventually dieing.
+
+-----
+plant_valid_wall() expects only a single parameter, "pos", which is a table
+indicating the X,Y,Z coordinates to search for nearby adjacent walls.  This
+function returns the location of the first wall found as a facedir value, or
+nil if there are no adjacent walls.
+
+-----
+is_node_loaded() is defined in exactly the same manner (that is, "node_pos" is
+a set of coordinates), and acts as a wrapper for the
+minetest.env:get_node_or_nil(node_pos) function.  Returns true if the node in
+question is already loaded, or false if not.
+
+-----
+dbg() is a simple debug output function which takes one string parameter.  It
+just checks if plantlife_debug is true and outputs the phrase "[Plantlife] "
+followed by the supplied string, via the print() function.
+
+
+===============
+Global Settings
+===============
+
+These first three allow you to turn the various classes of plants on or off.
+By default, all three are "true", thus turning all three classes on.
+
+	enable_flowers = true
+	enable_junglegrass = true
+	enable_poisonivy = true
+
+Enable this if you want the mod to spam your console with debug info :-)
+
+	plantlife_debug = false
+
+The mod uses perlin noise to create "biomes" of the various plants.  Aside
+from plantlife_seed_diff (see below), these values are the ones plugged 
+directly into the minetest.env:get_perlin() function.  For more information on
+how perlin noise is generated, you will need to search the web, as these
+default values were arrived at through trial and error.
+
+	plantlife_seed_diff = 123
+	perlin_octaves = 3
+	perlin_persistence = 0.2
+	perlin_scale = 25
+
+This value is compared against the output of the above perlin noise function
+to decide when to actually place a plant.  Smaller numbers mean larger biomes
+and more abundant plants.
+
+	plantlife_limit = 0.6
+
+These two control the basic ABM settings for spawning plants - spawn_delay 
+is used as the 'interval' parameter and controls how often to run the ABM (in
+in-game tenths of seconds), while spawn_chance is used for the ABM's "chance"
+parameter, and is basically how likely the ABM is to actually execute
+(a 1:(1/chance) probability).
+
+	spawn_delay = 2000
+	spawn_chance = 100
+
+These next two control the same two settings used by the growing ABM.
+
+	grow_delay = 1000
+	grow_chance = 10
+
+These three are pretty obvious :-)
+
+	flowers_seed_diff = plantlife_seed_diff
+	junglegrass_seed_diff = plantlife_seed_diff + 10
+	poisonivy_seed_diff = plantlife_seed_diff + 10
+