From 0f25c621fcb05bd2cea0b8fb8abd3c33a2e263b2 Mon Sep 17 00:00:00 2001 From: Vanessa Ezekowitz Date: Sat, 1 Dec 2012 19:26:53 -0500 Subject: [PATCH] Added API documentation. --- API.txt | 152 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 API.txt diff --git a/API.txt b/API.txt new file mode 100644 index 0000000..5a4c5c9 --- /dev/null +++ b/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 +