Added API documentation.

This commit is contained in:
Vanessa Ezekowitz 2012-12-01 19:26:53 -05:00
parent af7c2894ae
commit 0f25c621fc

152
API.txt Normal file
View File

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