plantlife_modpack/API.txt

This document briefly describes the Plantlife API.

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

There are five main functions defined by the main "plants_lib" 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.  All of the variables below, if specified at all, must be
specified exactly in the order given here.

spawn_on_surfaces = function(sdelay, splant, sradius, schance, ssurface,
		    savoid, seed_diff, lightmin, lightmax, nneighbors,
		    ocount, facedir, depthmax, altitudemin, altitudemax)

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, 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"}.

From here down are several optional parameters.  You can use as many as you
need, but you must specify them in order (so if you want lightmax, you need
lightmin and seed_diff also, but not the rest).

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 around 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.

-----
The second function, grow_plants() 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)

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, 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".

-----
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
===============

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