226 lines
9.8 KiB
Plaintext
226 lines
9.8 KiB
Plaintext
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. 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)
|
|
|
|
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 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 (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 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.
|
|
|
|
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.
|
|
|
|
-----
|
|
The second 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, 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.
|
|
|
|
-----
|
|
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
|
|
|