forked from mtcontrib/plantlife_modpack
348 lines
15 KiB
Plaintext
348 lines
15 KiB
Plaintext
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 with two parameters: a table with the biome information, and
|
|
a string or table describing what to execute if the engine finds a suitable
|
|
node (see below):
|
|
|
|
plantslib:register_generate_plant(biome, function_or_treedef)
|
|
|
|
Where "biome" is a table containing about a dozen variables:
|
|
|
|
biome = {
|
|
surface = "string", -- [*] what nodes to spawn on.
|
|
avoid_nodes = {table}, -- [*] what nodes to avoid when spawning.
|
|
avoid_radius = num, -- [*] how much distance to leave between
|
|
the object to be added and the objects
|
|
to be avoided.
|
|
rarity = num, -- how rare should this tree be in its biome?
|
|
Larger values more rare, determined by
|
|
math.random(1,100) > this
|
|
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, -- coldest allowable temperature for a plant
|
|
to spawn (that is, the highest Perlin
|
|
temperature map value).
|
|
temp_max = num, -- warmest allowable temperature to spawn a
|
|
plant (lowest Perlin temperature value).
|
|
}
|
|
|
|
[*] 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.
|
|
|
|
Regarding function_or_treedef, this must either be a string indicating the
|
|
name of the function that should be called if a suitable spawn location has
|
|
been found, OR a table with an L-Systems tree definition.
|
|
|
|
If you specify a string with a function name, that function will be passed a
|
|
single position parameter (in the usual table format), indicating where the
|
|
object should be placed. If you specified an L-Systems tree definition, then
|
|
that definition will be passed directly to the spawn_tree() function along
|
|
with the position to spawn the tree on.
|
|
|
|
-----
|
|
|
|
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, seed_diff)
|
|
|
|
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: One of these nodes 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. This is so that the plant can be manually placed
|
|
on something like a flower pot or something without it growing
|
|
and eventually dieing. Defaults to "default:dirt_with_grass".
|
|
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: String indicating what function to use to grow the plant, if
|
|
any, or a table with an L-Systems tree model, or nil. If it's
|
|
nil, If it's nil, a regular plant will be inserted in place
|
|
of the one being grown, per the above variables. If it's a
|
|
string, the function named therein is executed and passed a
|
|
parameter for the current position, followed by the "can grow
|
|
here" and temperature map Perlin values at that location. If
|
|
it's a table, the tree described by that table is spawned at
|
|
the current position. In both string and table cases, all
|
|
parameters from gresult to ground_nodes, except for
|
|
grow_nodes, are ignored.
|
|
seed_diff: The Perlin seed diff to be use to calculate the first 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.
|
|
|