API.txt

This document briefly describes the Plantlife API.

Last revision: 2013-01-18

=========
Functions
=========

All functions in plants lib are declared locally to avoid namespace collisions
with other mods.  They are accessible via the "plantslib" method, e.g.
plantslib:spawn_on_surfaces() and so forth.

There are three main functions defined by the main "plants_lib" mod:

spawn_on_surfaces()
generate_on_surfaces()
grow_plants()

There are also several internal, helper functions that can be called if so
desired, but they are not really intended for use by other mods and may change
at any time.  See init.lua for more.

-----

The first of these, spawn_on_surfaces() is defined with quite a large number
of variables.  All of the variables below, if specified at all, must be
specified exactly in the order given here.  This function has no return value.

spawn_on_surfaces = function(sdelay, splant, sradius, schance, ssurface,
	savoid, seed_diff, lightmin, lightmax, nneighbors, ocount, facedir,
	depthmax, altitudemin, altitudemax, sbiome, sbiomesize, sbiomecount, 
	airsize, aircount, tempmin, tempmax)

The first several of these are all required, and are from the last version of
the flowers mod, so this part of the API should be the same as before.

sdelay:		The value passed to the ABM's interval parameter, in seconds.
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 (1-in-X chance of operating on a given
		node, e.g. 1-in-10).
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 and where it should
		operate.
savoid:		Table with a list of groups and/or node names to avoid
		when spawning the plant, such as {"group:flowers",
		"default:tree"}.

From here down are several optional parameters.  You can use as many as you
need, but you must specify them in order.  To keep the default values for
those parameters you don't wish to alter, set them to nil in your function
call.

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.  Defaults to 0 if not
		provided.
lightmin:	Minimum amount of light necessary to make a plant spawn.
		Defaults to 0.
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"}.  Defaults to the
		value of ssurface if not provided.
ocount:		There must be at least this many of the above neighbors in
		the eight spaces immediately surrounding the node the
		plant is about to spawn on for it to happen.  Defaults to
		0.
facedir:	The value passed to the param2 variable when adding the
		plant node to the map.  Defaults to 0.
depthmax:	If a node spawns on top of a water source, the water must
		be at most this deep.  Defaults to 1 node.
altitudemin:	Items must be at this altitude or higher to spawn at all.
		Defaults to -31000.
altitudemax:	But no higher than this altitude.  Defaults to +31000.
sbiome:		List of nodes that must be somewhere in the vicinity in
		order for the plant to spawn.  Typically this would be 
		something like "default:water_source" or "default:sand".
		Defaults to the value of ssurface if not provided.
sbiomesize:	How large of an area to check for the above node.
		Specifically, this checks a cuboid area centered on the
		node to be spawned on, 3 tall and this wide/long.
		Defaults to 0.
sbiomecount:	How many of the above nodes must be within that radius.
		Defaults to 1.
airradius:	How large of an area to check for air around the target.
		Defaults to 0 (only check the target).
aircount:	How many of the surrounding nodes need to be air for the
		above check to return true.  Defaults to 1.
tempmin:	Minimum 2d Perlin value (which has a floating point range of
		-1 to +1) needed in the temperature map for the desired
		plant to spawn.  Defaults to -1 if not supplied.
tempmax:	Maximum temperature.  Defaults to +1.

By default, if a biome node, size, and count are not defined, the biome
checking is disabled.  Same holds true for the nneighbors bit above that.

-----

To register a plant to be spawned at mapgen time rather than via an ABM, call
this function:

plantslib:register_generate_plant(biome)

Where "biome" is a table containing about a dozen variables:

biome = {
	surface = "string",	-- [*] what nodes to spawn on.
	avoid =	{table},	-- [*] what nodes to avoid when spawning.
	radius = num,		-- [*] how much distance to leave between
				       the object to be added and the objects
				       to be avoided.
	seed_diff = num,	-- perlin seed-diff value.  Defaults to 0, 
				   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.
	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.
	depth = num,		-- how deep/thick of a layer the spawned-on
				   node must be.  Typically used for water.
				   Defaults to unlimited.
	min_elevation = num,	-- minimum elevation in meters/nodes.
				   Defaults to -31000 (unlimited).
	max_elevation = num,	-- maximum elevation.  Defaults to +31000
				   (unlimited).
	near_nodes = {table},	-- what nodes must be in the general vicinity
				   of the object being spawned.
	near_nodes_size = num,	-- how wide of a search area to look for 
				   the nodes in that list.
	near_nodes_count = num,	-- at least this many of those nodes must be
				   in the area.
	temp_min = num,		-- minimum perlin temperature value needed to
				   spawn an object (represents the hottest
				   allowable temperature).
	temp_max = num,		-- maximum perlin temperature value (coldest
				   allowable temperature).
	exec_funct = "string",	-- [**] name of the function to use to
					actually build the object if the code
					decides it is time to do so.
}

[*] These entries are required for the spawn code to work.  Everything else
    is optional.  Unless explicitly stated, all unused/unsupplied parameters
    default to nil and will not affect the results of the code.

[**] A string indicating the name of the function that should be called if a
     suitable spawn location has been found.  This function will be passed a
     single parameter, pos, indicating where the object should be placed.

-----

The third function, grow_plants() is used to turn the spawned nodes above
into something else over time.  This function has no return value, and is
defined like so:

grow_plants = function(gdelay, gchance, gplant, gresult, dry_early_node,
	grow_nodes, facedir, need_wall, grow_vertically, height_limit,
	ground_nodes, grow_function)

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.
facedir:	Same as with spawning a plant.  If supplied, this value is
		passed to the param2 variable when changing the plant.  If
		nil or left out, no new param2 value is applied.
need_wall:	Set this to true if you the plant needs to grow against a
		wall.  Defaults to false.
grow_vertically: Set this to true if the plant needs to grow vertically, as
		in climbing poison ivy.  Defaults to false.
height_limit:	Just how tall can a vertically-growing plant go?  Set this
		accordingly.  The mod will search straight down from the
		position being spawned at to find a ground node, set via the
		parameter below. Defaults to 62000 (unlimited).
ground_nodes:	What nodes should be treated as "the ground" below a
		vertically-growing plant.  Usually this will be the same
		as the grow_nodes table, but might also include, for
		example, water or some other surrounding material.
		Defaults to "default:dirt_with_grass".
grow_function:	Execute the named function (which must be supplied as just
		the name of the function as a string) when growing this
		node, rather than using the method provided by the default
		growing code.  Note that if this is specified, only the
		gdelay, gchance, and gplant variables will be used, the
		rest will be ignored by the growing ABM.  You can still
		read them from within the function if you need to.  The
		function will be passed two parameters in order:  The
		position of the node to be "grown" (in the usual table
		format), and the Perlin noise value at the location in
		question.
seed_diff:	The Perlin seed diff to be use to calculate the noise 
		value given to the above grow_function.  Should be the
		same as the seed diff used when first spawning the plant
		that's being grown.

-----

Of the few helper functions, plant_valid_wall() expects only a single
parameter, "pos", which is the usual table indicating the coordinates around
which to search for 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
===============

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 three are pretty obvious.  Basically they control the shape and 
distribution of the biomes in which the various plants will appear.

	flowers_seed_diff = plantlife_seed_diff
	junglegrass_seed_diff = plantlife_seed_diff + 10
	poisonivy_seed_diff = plantlife_seed_diff + 10

==============
Local settings
==============

Each of the three components of this modpack has an init.lua file, as usual,
and at the top of those files are four variables that affect how and when the
ABMs are run.  In each one, the spawn_delay value 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 to (1/chance)
probability).

	spawn_delay = 2000
	spawn_chance = 100

The other two in each init.lua file control the same two settings used by the
growing ABM.

	grow_delay = 1000
	grow_chance = 10

===================
Temperature Mapping
===================

This mod uses Perlin noise to establish a rough temperature map, with values
taken from Splizard's Snow Biomes mod so that the two will be compatible,
since that mod appears to be the standard now.

The way Perlin values are used by this mod, in keeping with the snow mod's 
apparent methods, larger values returned by the Perlin function represent
*colder* temperatures.  In this mod, the following table gives a rough
approximation of how temperature maps to these values, normalized to
0.53 = 0 °C and +1.0 = -25 °C.

Perlin		Approx. Temperature
-1.0		 81 °C	( 178 °F)
-0.75		 68 °C	( 155 °F)
-0.56		 58 °C	( 136 °F)
-0.5		 55 °C	( 131 °F)
-0.25		 41 °C	( 107 °F)
-0.18		 38 °C	( 100 °F)
 0		 28 °C	(  83 °F)
 0.13		 21 °C	(  70 °F)
 0.25		 15 °C	(  59 °F)
 0.5		  2 °C	(  35 °F)
 0.53		  0 °C	(  32 °F)
 0.75		-12 °C	(  11 °F)
 0.86		-18 °C	(   0 °F)
 1.0		-25 °C	(- 13 °F)

Included in this table are even 0.25 steps in Perlin values along with some
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.