1622 lines
61 KiB
Plaintext
1622 lines
61 KiB
Plaintext
Minetest Lua Modding API Reference 0.4.4
|
|
==========================================
|
|
More information at http://c55.me/minetest/
|
|
|
|
Introduction
|
|
-------------
|
|
Content and functionality can be added to Minetest 0.4 by using Lua
|
|
scripting in run-time loaded mods.
|
|
|
|
A mod is a self-contained bunch of scripts, textures and other related
|
|
things that is loaded by and interfaces with Minetest.
|
|
|
|
Mods are contained and ran solely on the server side. Definitions and media
|
|
files are automatically transferred to the client.
|
|
|
|
If you see a deficiency in the API, feel free to attempt to add the
|
|
functionality in the engine and API. You can send such improvements as
|
|
source code patches to <celeron55@gmail.com>.
|
|
|
|
Programming in Lua
|
|
-------------------
|
|
If you have any difficulty in understanding this, please read:
|
|
http://www.lua.org/pil/
|
|
|
|
Startup
|
|
--------
|
|
Mods are loaded during server startup from the mod load paths by running
|
|
the init.lua scripts in a shared environment.
|
|
|
|
Mod load path
|
|
-------------
|
|
Generic:
|
|
$path_share/games/gameid/mods/
|
|
$path_share/mods/gameid/
|
|
$path_user/games/gameid/mods/
|
|
$path_user/mods/gameid/ <-- User-installed mods
|
|
$worldpath/worldmods/
|
|
|
|
In a run-in-place version (eg. the distributed windows version):
|
|
minetest-0.4.x/games/gameid/mods/
|
|
minetest-0.4.x/mods/gameid/ <-- User-installed mods
|
|
minetest-0.4.x/worlds/worldname/worldmods/
|
|
|
|
On an installed version on linux:
|
|
/usr/share/minetest/games/gameid/mods/
|
|
~/.minetest/mods/gameid/ <-- User-installed mods
|
|
~/.minetest/worlds/worldname/worldmods
|
|
|
|
Mod load path for world-specific games
|
|
--------------------------------------
|
|
It is possible to include a game in a world; in this case, no mods or
|
|
games are loaded or checked from anywhere else.
|
|
|
|
This is useful for eg. adventure worlds.
|
|
|
|
This happens if the following directory exists:
|
|
$world/game/
|
|
|
|
Mods should be then be placed in:
|
|
$world/game/mods/
|
|
|
|
Modpack support
|
|
----------------
|
|
Mods can be put in a subdirectory, if the parent directory, which otherwise
|
|
should be a mod, contains a file named modpack.txt. This file shall be
|
|
empty, except for lines starting with #, which are comments.
|
|
|
|
Mod directory structure
|
|
------------------------
|
|
mods
|
|
|-- modname
|
|
| |-- depends.txt
|
|
| |-- init.lua
|
|
| |-- textures
|
|
| | |-- modname_stuff.png
|
|
| | `-- modname_something_else.png
|
|
| |-- sounds
|
|
| |-- media
|
|
| `-- <custom data>
|
|
`-- another
|
|
|
|
modname:
|
|
The location of this directory can be fetched by using
|
|
minetest.get_modpath(modname)
|
|
|
|
depends.txt:
|
|
List of mods that have to be loaded before loading this mod.
|
|
A single line contains a single modname.
|
|
|
|
init.lua:
|
|
The main Lua script. Running this script should register everything it
|
|
wants to register. Subsequent execution depends on minetest calling the
|
|
registered callbacks.
|
|
|
|
minetest.setting_get(name) and minetest.setting_getbool(name) can be used
|
|
to read custom or existing settings at load time, if necessary.
|
|
|
|
textures, sounds, media:
|
|
Media files (textures, sounds, whatever) that will be transferred to the
|
|
client and will be available for use by the mod.
|
|
|
|
Naming convention for registered textual names
|
|
----------------------------------------------
|
|
Registered names should generally be in this format:
|
|
"modname:<whatever>" (<whatever> can have characters a-zA-Z0-9_)
|
|
|
|
This is to prevent conflicting names from corrupting maps and is
|
|
enforced by the mod loader.
|
|
|
|
Example: mod "experimental", ideal item/node/entity name "tnt":
|
|
-> the name should be "experimental:tnt".
|
|
|
|
Enforcement can be overridden by prefixing the name with ":". This can
|
|
be used for overriding the registrations of some other mod.
|
|
|
|
Example: Any mod can redefine experimental:tnt by using the name
|
|
":experimental:tnt" when registering it.
|
|
(also that mod is required to have "experimental" as a dependency)
|
|
|
|
The ":" prefix can also be used for maintaining backwards compatibility.
|
|
|
|
Aliases
|
|
-------
|
|
Aliases can be added by using minetest.register_alias(name, convert_to)
|
|
|
|
This will make Minetest to convert things called name to things called
|
|
convert_to.
|
|
|
|
This can be used for maintaining backwards compatibility.
|
|
|
|
This can be also used for setting quick access names for things, eg. if
|
|
you have an item called epiclylongmodname:stuff, you could do
|
|
minetest.register_alias("stuff", "epiclylongmodname:stuff")
|
|
and be able to use "/giveme stuff".
|
|
|
|
Textures
|
|
--------
|
|
Mods should generally prefix their textures with modname_, eg. given
|
|
the mod name "foomod", a texture could be called
|
|
"foomod_foothing.png"
|
|
|
|
Textures are referred to by their complete name, or alternatively by
|
|
stripping out the file extension:
|
|
eg. foomod_foothing.png
|
|
eg. foomod_foothing
|
|
|
|
Sounds
|
|
-------
|
|
Only OGG files are supported.
|
|
|
|
For positional playing of sounds, only single-channel (mono) files are
|
|
supported. Otherwise OpenAL will play them non-positionally.
|
|
|
|
Mods should generally prefix their sounds with modname_, eg. given
|
|
the mod name "foomod", a sound could be called
|
|
"foomod_foosound.ogg"
|
|
|
|
Sounds are referred to by their name with a dot, a single digit and the
|
|
file extension stripped out. When a sound is played, the actual sound file
|
|
is chosen randomly from the matching sounds.
|
|
|
|
When playing the sound "foomod_foosound", the sound is chosen randomly
|
|
from the available ones of the following files:
|
|
foomod_foosound.ogg
|
|
foomod_foosound.0.ogg
|
|
foomod_foosound.1.ogg
|
|
...
|
|
foomod_foosound.9.ogg
|
|
|
|
Examples of sound parameter tables:
|
|
-- Play locationless on all clients
|
|
{
|
|
gain = 1.0, -- default
|
|
}
|
|
-- Play locationless to a player
|
|
{
|
|
to_player = name,
|
|
gain = 1.0, -- default
|
|
}
|
|
-- Play in a location
|
|
{
|
|
pos = {x=1,y=2,z=3},
|
|
gain = 1.0, -- default
|
|
max_hear_distance = 32, -- default
|
|
}
|
|
-- Play connected to an object, looped
|
|
{
|
|
object = <an ObjectRef>,
|
|
gain = 1.0, -- default
|
|
max_hear_distance = 32, -- default
|
|
loop = true, -- only sounds connected to objects can be looped
|
|
}
|
|
|
|
SimpleSoundSpec:
|
|
eg. ""
|
|
eg. "default_place_node"
|
|
eg. {}
|
|
eg. {name="default_place_node"}
|
|
eg. {name="default_place_node", gain=1.0}
|
|
|
|
Registered definitions of stuff
|
|
--------------------------------
|
|
Anything added using certain minetest.register_* functions get added to
|
|
the global minetest.registered_* tables.
|
|
|
|
minetest.register_entity(name, prototype table)
|
|
-> minetest.registered_entities[name]
|
|
|
|
minetest.register_node(name, node definition)
|
|
-> minetest.registered_items[name]
|
|
-> minetest.registered_nodes[name]
|
|
|
|
minetest.register_tool(name, item definition)
|
|
-> minetest.registered_items[name]
|
|
|
|
minetest.register_craftitem(name, item definition)
|
|
-> minetest.registered_items[name]
|
|
|
|
Note that in some cases you will stumble upon things that are not contained
|
|
in these tables (eg. when a mod has been removed). Always check for
|
|
existence before trying to access the fields.
|
|
|
|
Example: If you want to check the drawtype of a node, you could do:
|
|
|
|
local function get_nodedef_field(nodename, fieldname)
|
|
if not minetest.registered_nodes[nodename] then
|
|
return nil
|
|
end
|
|
return minetest.registered_nodes[nodename][fieldname]
|
|
end
|
|
local drawtype = get_nodedef_field(nodename, "drawtype")
|
|
|
|
Example: minetest.get_item_group(name, group) has been implemented as:
|
|
|
|
function minetest.get_item_group(name, group)
|
|
if not minetest.registered_items[name] or not
|
|
minetest.registered_items[name].groups[group] then
|
|
return 0
|
|
end
|
|
return minetest.registered_items[name].groups[group]
|
|
end
|
|
|
|
Nodes
|
|
------
|
|
Nodes are the bulk data of the world: cubes and other things that take the
|
|
space of a cube. Huge amounts of them are handled efficiently, but they
|
|
are quite static.
|
|
|
|
The definition of a node is stored and can be accessed by name in
|
|
minetest.registered_nodes[node.name]
|
|
See "Registered definitions of stuff".
|
|
|
|
Nodes are passed by value between Lua and the engine.
|
|
They are represented by a table:
|
|
{name="name", param1=num, param2=num}
|
|
|
|
param1 and param2 are 8 bit integers. The engine uses them for certain
|
|
automated functions. If you don't use these functions, you can use them to
|
|
store arbitrary values.
|
|
|
|
The functions of param1 and param2 are determined by certain fields in the
|
|
node definition:
|
|
param1 is reserved for the engine when paramtype != "none":
|
|
paramtype = "light"
|
|
^ The value stores light with and without sun in it's
|
|
upper and lower 4 bits.
|
|
param2 is reserved for the engine when any of these are used:
|
|
liquidtype == "flowing"
|
|
^ The level and some flags of the liquid is stored in param2
|
|
drawtype == "flowingliquid"
|
|
^ The drawn liquid level is read from param2
|
|
drawtype == "torchlike"
|
|
drawtype == "signlike"
|
|
paramtype2 == "wallmounted"
|
|
^ The rotation of the node is stored in param2. You can make this value
|
|
by using minetest.dir_to_wallmounted().
|
|
paramtype2 == "facedir"
|
|
^ The rotation of the node is stored in param2. Furnaces and chests are
|
|
rotated this way. Can be made by using minetest.dir_to_facedir().
|
|
|
|
Nodes can also contain extra data. See "Node Metadata".
|
|
|
|
Node drawtypes
|
|
---------------
|
|
There are a bunch of different looking node types. These are mostly just
|
|
copied from Minetest 0.3; more may be made in the future.
|
|
|
|
Look for examples in games/minimal or games/minetest_game.
|
|
|
|
- normal
|
|
- airlike
|
|
- liquid
|
|
- flowingliquid
|
|
- glasslike
|
|
- allfaces
|
|
- allfaces_optional
|
|
- torchlike
|
|
- signlike
|
|
- plantlike
|
|
- fencelike
|
|
- raillike
|
|
- nodebox -- See below. EXPERIMENTAL
|
|
|
|
Node boxes
|
|
-----------
|
|
Node selection boxes are defined using "node boxes"
|
|
|
|
The "nodebox" node drawtype allows defining visual of nodes consisting of
|
|
arbitrary number of boxes. It allows defining stuff like stairs. Only the
|
|
"fixed" box type is supported for these.
|
|
^ Please note that this is still experimental, and may be incompatibly
|
|
changed in the future.
|
|
|
|
A nodebox is defined as any of:
|
|
{
|
|
-- A normal cube; the default in most things
|
|
type = "regular"
|
|
}
|
|
{
|
|
-- A fixed box (facedir param2 is used, if applicable)
|
|
type = "fixed",
|
|
fixed = box OR {box1, box2, ...}
|
|
}
|
|
{
|
|
-- A box like the selection box for torches
|
|
-- (wallmounted param2 is used, if applicable)
|
|
type = "wallmounted",
|
|
wall_top = box,
|
|
wall_bottom = box,
|
|
wall_side = box
|
|
}
|
|
|
|
A box is defined as:
|
|
{x1, y1, z1, x2, y2, z2}
|
|
A box of a regular node would look like:
|
|
{-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},
|
|
|
|
Representations of simple things
|
|
--------------------------------
|
|
Position/vector:
|
|
{x=num, y=num, z=num}
|
|
Currently the API does not provide any helper functions for addition,
|
|
subtraction and whatever; you can define those that you need yourself.
|
|
|
|
pointed_thing:
|
|
{type="nothing"}
|
|
{type="node", under=pos, above=pos}
|
|
{type="object", ref=ObjectRef}
|
|
|
|
Items
|
|
------
|
|
Node (register_node):
|
|
A node from the world
|
|
Tool (register_tool):
|
|
A tool/weapon that can dig and damage things according to tool_capabilities
|
|
Craftitem (register_craftitem):
|
|
A miscellaneous item
|
|
|
|
Items and item stacks can exist in three formats:
|
|
|
|
Serialized; This is called stackstring or itemstring:
|
|
eg. 'default:dirt 5'
|
|
eg. 'default:pick_wood 21323'
|
|
eg. 'default:apple'
|
|
|
|
Table format:
|
|
eg. {name="default:dirt", count=5, wear=0, metadata=""}
|
|
^ 5 dirt nodes
|
|
eg. {name="default:pick_wood", count=1, wear=21323, metadata=""}
|
|
^ a wooden pick about 1/3 weared out
|
|
eg. {name="default:apple", count=1, wear=0, metadata=""}
|
|
^ an apple.
|
|
|
|
ItemStack:
|
|
C++ native format with many helper methods. Useful for converting between
|
|
formats. See the Class reference section for details.
|
|
|
|
When an item must be passed to a function, it can usually be in any of
|
|
these formats.
|
|
|
|
Groups
|
|
-------
|
|
In a number of places, there is a group table. Groups define the
|
|
properties of a thing (item, node, armor of entity, capabilities of
|
|
tool) in such a way that the engine and other mods can can interact with
|
|
the thing without actually knowing what the thing is.
|
|
|
|
Usage:
|
|
- Groups are stored in a table, having the group names with keys and the
|
|
group ratings as values. For example:
|
|
groups = {crumbly=3, soil=1}
|
|
^ Default dirt (soil group actually currently not defined; TODO)
|
|
groups = {crumbly=2, soil=1, level=2, outerspace=1}
|
|
^ A more special dirt-kind of thing
|
|
- Groups always have a rating associated with them. If there is no
|
|
useful meaning for a rating for an enabled group, it shall be 1.
|
|
- When not defined, the rating of a group defaults to 0. Thus when you
|
|
read groups, you must interpret nil and 0 as the same value, 0.
|
|
|
|
You can read the rating of a group for an item or a node by using
|
|
minetest.get_item_group(itemname, groupname)
|
|
|
|
Groups of items
|
|
----------------
|
|
Groups of items can define what kind of an item it is (eg. wool).
|
|
|
|
Groups of nodes
|
|
----------------
|
|
In addition to the general item things, groups are used to define whether
|
|
a node is destroyable and how long it takes to destroy by a tool.
|
|
|
|
Groups of entities
|
|
-------------------
|
|
For entities, groups are, as of now, used only for calculating damage.
|
|
|
|
object.get_armor_groups() -> a group-rating table (eg. {fleshy=3})
|
|
object.set_armor_groups({level=2, fleshy=2, cracky=2})
|
|
|
|
Groups of tools
|
|
----------------
|
|
Groups in tools define which groups of nodes and entities they are
|
|
effective towards.
|
|
|
|
Groups in crafting recipes
|
|
---------------------------
|
|
An example: Make meat soup from any meat, any water and any bowl
|
|
{
|
|
output = 'food:meat_soup_raw',
|
|
recipe = {
|
|
{'group:meat'},
|
|
{'group:water'},
|
|
{'group:bowl'},
|
|
},
|
|
-- preserve = {'group:bowl'}, -- Not implemented yet (TODO)
|
|
}
|
|
An another example: Make red wool from white wool and red dye
|
|
{
|
|
type = 'shapeless',
|
|
output = 'wool:red',
|
|
recipe = {'wool:white', 'group:dye,basecolor_red'},
|
|
}
|
|
|
|
Special groups
|
|
---------------
|
|
- immortal: Disables the group damage system for an entity
|
|
- level: Can be used to give an additional sense of progression in the game.
|
|
- A larger level will cause eg. a weapon of a lower level make much less
|
|
damage, and get weared out much faster, or not be able to get drops
|
|
from destroyed nodes.
|
|
- 0 is something that is directly accessible at the start of gameplay
|
|
- There is no upper limit
|
|
- dig_immediate: (player can always pick up node without tool wear)
|
|
- 2: node is removed without tool wear after 0.5 seconds or so
|
|
(rail, sign)
|
|
- 3: node is removed without tool wear immediately (torch)
|
|
- disable_jump: Player (and possibly other things) cannot jump from node
|
|
- fall_damage_add_percent: damage speed = speed * (1 + value/100)
|
|
- bouncy: value is bounce speed in percent
|
|
- falling_node: if there is no walkable block under the node it will fall
|
|
- attached_node: if the node under it is not a walkable block the node will be
|
|
dropped as an item. If the node is wallmounted the
|
|
wallmounted direction is checked.
|
|
|
|
Known damage and digging time defining groups
|
|
----------------------------------------------
|
|
Valid ratings for these are 0, 1, 2 and 3, unless otherwise stated.
|
|
- crumbly: dirt, sand
|
|
- cracky: tough but crackable stuff like stone.
|
|
- snappy: something that can be cut using fine tools; eg. leaves, small
|
|
plants, wire, sheets of metal
|
|
- choppy: something that can be cut using force; eg. trees, wooden planks
|
|
- fleshy: Living things like animals and the player. This could imply
|
|
some blood effects when hitting.
|
|
- explody: Especially prone to explosions
|
|
- oddly_breakable_by_hand:
|
|
Can be added to nodes that shouldn't logically be breakable by the
|
|
hand but are. Somewhat similar to dig_immediate, but times are more
|
|
like {[1]=3.50,[2]=2.00,[3]=0.70} and this does not override the
|
|
speed of a tool if the tool can dig at a faster speed than this
|
|
suggests for the hand.
|
|
|
|
Examples of custom groups
|
|
--------------------------
|
|
Item groups are often used for defining, well, //groups of items//.
|
|
- meat: any meat-kind of a thing (rating might define the size or healing
|
|
ability or be irrelevant - it is not defined as of yet)
|
|
- eatable: anything that can be eaten. Rating might define HP gain in half
|
|
hearts.
|
|
- flammable: can be set on fire. Rating might define the intensity of the
|
|
fire, affecting eg. the speed of the spreading of an open fire.
|
|
- wool: any wool (any origin, any color)
|
|
- metal: any metal
|
|
- weapon: any weapon
|
|
- heavy: anything considerably heavy
|
|
|
|
Digging time calculation specifics
|
|
-----------------------------------
|
|
Groups such as **crumbly**, **cracky** and **snappy** are used for this
|
|
purpose. Rating is 1, 2 or 3. A higher rating for such a group implies
|
|
faster digging time.
|
|
|
|
The **level** group is used to limit the toughness of nodes a tool can dig
|
|
and to scale the digging times / damage to a greater extent.
|
|
|
|
^ PLEASE DO UNDERSTAND THIS, otherwise you cannot use the system to it's
|
|
full potential.
|
|
|
|
Tools define their properties by a list of parameters for groups. They
|
|
cannot dig other groups; thus it is important to use a standard bunch of
|
|
groups to enable interaction with tools.
|
|
|
|
**Tools define:**
|
|
* Full punch interval
|
|
* Maximum drop level
|
|
* For an arbitrary list of groups:
|
|
* Uses (until the tool breaks)
|
|
* Maximum level (usually 0, 1, 2 or 3)
|
|
* Digging times
|
|
|
|
**Full punch interval**:
|
|
When used as a weapon, the tool will do full damage if this time is spent
|
|
between punches. If eg. half the time is spent, the tool will do half
|
|
damage.
|
|
|
|
**Maximum drop level**
|
|
Suggests the maximum level of node, when dug with the tool, that will drop
|
|
it's useful item. (eg. iron ore to drop a lump of iron).
|
|
- This is not automated; it is the responsibility of the node definition
|
|
to implement this
|
|
|
|
**Uses**
|
|
Determines how many uses the tool has when it is used for digging a node,
|
|
of this group, of the maximum level. For lower leveled nodes, the use count
|
|
is multiplied by 3^leveldiff.
|
|
- uses=10, leveldiff=0 -> actual uses: 10
|
|
- uses=10, leveldiff=1 -> actual uses: 30
|
|
- uses=10, leveldiff=2 -> actual uses: 90
|
|
|
|
**Maximum level**
|
|
Tells what is the maximum level of a node of this group that the tool will
|
|
be able to dig.
|
|
|
|
**Digging times**
|
|
List of digging times for different ratings of the group, for nodes of the
|
|
maximum level.
|
|
* For example, as a lua table, ''times={2=2.00, 3=0.70}''. This would
|
|
result in the tool to be able to dig nodes that have a rating of 2 or 3
|
|
for this group, and unable to dig the rating 1, which is the toughest.
|
|
Unless there is a matching group that enables digging otherwise.
|
|
* For entities, damage equals the amount of nodes dug in the time spent
|
|
between hits, with a maximum time of ''full_punch_interval''.
|
|
|
|
Example definition of the capabilities of a tool
|
|
-------------------------------------------------
|
|
tool_capabilities = {
|
|
full_punch_interval=1.5,
|
|
max_drop_level=1,
|
|
groupcaps={
|
|
crumbly={maxlevel=2, uses=20, times={[1]=1.60, [2]=1.20, [3]=0.80}}
|
|
}
|
|
}
|
|
|
|
This makes the tool be able to dig nodes that fullfill both of these:
|
|
- Have the **crumbly** group
|
|
- Have a **level** group less or equal to 2
|
|
|
|
Table of resulting digging times:
|
|
crumbly 0 1 2 3 4 <- level
|
|
-> 0 - - - - -
|
|
1 0.80 1.60 1.60 - -
|
|
2 0.60 1.20 1.20 - -
|
|
3 0.40 0.80 0.80 - -
|
|
|
|
level diff: 2 1 0 -1 -2
|
|
|
|
Table of resulting tool uses:
|
|
-> 0 - - - - -
|
|
1 180 60 20 - -
|
|
2 180 60 20 - -
|
|
3 180 60 20 - -
|
|
|
|
Notes:
|
|
- At crumbly=0, the node is not diggable.
|
|
- At crumbly=3, the level difference digging time divider kicks in and makes
|
|
easy nodes to be quickly breakable.
|
|
- At level > 2, the node is not diggable, because it's level > maxlevel
|
|
|
|
Entity damage mechanism
|
|
------------------------
|
|
Damage calculation:
|
|
- Take the time spent after the last hit
|
|
- Limit time to full_punch_interval
|
|
- Take the damage groups and imagine a bunch of nodes that have them
|
|
- Damage in HP is the amount of nodes destroyed in this time.
|
|
|
|
Client predicts damage based on damage groups. Because of this, it is able to
|
|
give an immediate response when an entity is damaged or dies; the response is
|
|
pre-defined somehow (eg. by defining a sprite animation) (not implemented;
|
|
TODO).
|
|
- Currently a smoke puff will appear when an entity dies.
|
|
|
|
The group **immortal** completely disables normal damage.
|
|
|
|
Entities can define a special armor group, which is **punch_operable**. This
|
|
group disables the regular damage mechanism for players punching it by hand or
|
|
a non-tool item, so that it can do something else than take damage.
|
|
|
|
On the Lua side, every punch calls ''entity:on_punch(puncher,
|
|
time_from_last_punch, tool_capabilities, direction)''. This should never be
|
|
called directly, because damage is usually not handled by the entity itself.
|
|
* ''puncher'' is the object performing the punch. Can be nil. Should never be
|
|
accessed unless absolutely required, to encourage interoperability.
|
|
* ''time_from_last_punch'' is time from last punch (by puncher) or nil.
|
|
* ''tool_capabilities'' can be nil.
|
|
* ''direction'' is a unit vector, pointing from the source of the punch to
|
|
the punched object.
|
|
|
|
To punch an entity/object in Lua, call ''object:punch(puncher,
|
|
time_from_last_punch, tool_capabilities, direction)''.
|
|
* Return value is tool wear.
|
|
* Parameters are equal to the above callback.
|
|
* If ''direction'' is nil and ''puncher'' is not nil, ''direction'' will be
|
|
automatically filled in based on the location of ''puncher''.
|
|
|
|
Node Metadata
|
|
-------------
|
|
The instance of a node in the world normally only contains the three values
|
|
mentioned in "Nodes". However, it is possible to insert extra data into a
|
|
node. It is called "node metadata"; See "NodeMetaRef".
|
|
|
|
Metadata contains two things:
|
|
- A key-value store
|
|
- An inventory
|
|
|
|
Some of the values in the key-value store are handled specially:
|
|
- formspec: Defines a right-click inventory menu. See "Formspec".
|
|
- infotext: Text shown on the screen when the node is pointed at
|
|
|
|
Example stuff:
|
|
|
|
local meta = minetest.env:get_meta(pos)
|
|
meta:set_string("formspec",
|
|
"invsize[8,9;]"..
|
|
"list[context;main;0,0;8,4;]"..
|
|
"list[current_player;main;0,5;8,4;]")
|
|
meta:set_string("infotext", "Chest");
|
|
local inv = meta:get_inventory()
|
|
inv:set_size("main", 8*4)
|
|
print(dump(meta:to_table()))
|
|
meta:from_table({
|
|
inventory = {
|
|
main = {[1] = "default:dirt", [2] = "", [3] = "", [4] = "", [5] = "", [6] = "", [7] = "", [8] = "", [9] = "", [10] = "", [11] = "", [12] = "", [13] = "", [14] = "default:cobble", [15] = "", [16] = "", [17] = "", [18] = "", [19] = "", [20] = "default:cobble", [21] = "", [22] = "", [23] = "", [24] = "", [25] = "", [26] = "", [27] = "", [28] = "", [29] = "", [30] = "", [31] = "", [32] = ""}
|
|
},
|
|
fields = {
|
|
formspec = "invsize[8,9;]list[context;main;0,0;8,4;]list[current_player;main;0,5;8,4;]",
|
|
infotext = "Chest"
|
|
}
|
|
})
|
|
|
|
Formspec
|
|
--------
|
|
Formspec defines a menu. Currently not much else than inventories are
|
|
supported. It is a string, with a somewhat strange format.
|
|
|
|
Spaces and newlines can be inserted between the blocks, as is used in the
|
|
examples.
|
|
|
|
Examples:
|
|
- Chest:
|
|
invsize[8,9;]
|
|
list[context;main;0,0;8,4;]
|
|
list[current_player;main;0,5;8,4;]
|
|
- Furnace:
|
|
invsize[8,9;]
|
|
list[context;fuel;2,3;1,1;]
|
|
list[context;src;2,1;1,1;]
|
|
list[context;dst;5,1;2,2;]
|
|
list[current_player;main;0,5;8,4;]
|
|
- Minecraft-like player inventory
|
|
invsize[8,7.5;]
|
|
image[1,0.6;1,2;player.png]
|
|
list[current_player;main;0,3.5;8,4;]
|
|
list[current_player;craft;3,0;3,3;]
|
|
list[current_player;craftpreview;7,1;1,1;]
|
|
|
|
Elements:
|
|
|
|
size[<W>,<H>]
|
|
^ Define the size of the menu in inventory slots
|
|
^ deprecated: invsize[<W>,<H>;]
|
|
|
|
list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;]
|
|
list[<inventory location>;<list name>;<X>,<Y>;<W>,<H>;<starting item index>]
|
|
^ Show an inventory list
|
|
|
|
image[<X>,<Y>;<W>,<H>;<texture name>]
|
|
^ Show an image
|
|
^ Position and size units are inventory slots
|
|
|
|
item_image[<X>,<Y>;<W>,<H>;<item name>]
|
|
^ Show an inventory image of registered item/node
|
|
^ Position and size units are inventory slots
|
|
|
|
background[<X>,<Y>;<W>,<H>;<texture name>]
|
|
^ Use a background. Inventory rectangles are not drawn then.
|
|
^ Position and size units are inventory slots
|
|
^ Example for formspec 8x4 in 16x resolution: image shall be sized 8*16px x 4*16px
|
|
|
|
field[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]
|
|
^ Textual field; will be sent to server when a button is clicked
|
|
^ x and y position the field relative to the top left of the menu
|
|
^ w and h are the size of the field
|
|
^ fields are a set height, but will be vertically centred on h
|
|
^ Position and size units are inventory slots
|
|
^ name is the name of the field as returned in fields to on_receive_fields
|
|
^ label, if not blank, will be text printed on the top left above the field
|
|
^ default is the default value of the field
|
|
^ default may contain variable references such as '${text}' which
|
|
will fill the value from the metadata value 'text'
|
|
^ Note: no extra text or more than a single variable is supported ATM.
|
|
|
|
field[<name>;<label>;<default>]
|
|
^ as above but without position/size units
|
|
^ special field for creating simple forms, such as sign text input
|
|
^ must be used without a size[] element
|
|
^ a 'Proceed' button will be added automatically
|
|
|
|
textarea[<X>,<Y>;<W>,<H>;<name>;<label>;<default>]
|
|
^ same as fields above, but with multi-line input
|
|
|
|
label[<X>,<Y>;<label>]
|
|
^ x and y work as per field
|
|
^ label is the text on the label
|
|
^ Position and size units are inventory slots
|
|
|
|
button[<X>,<Y>;<W>,<H>;<name>;<label>]
|
|
^ Clickable button. When clicked, fields will be sent.
|
|
^ x, y and name work as per field
|
|
^ w and h are the size of the button
|
|
^ label is the text on the button
|
|
^ Position and size units are inventory slots
|
|
|
|
image_button[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]
|
|
^ x, y, w, h, and name work as per button
|
|
^ image is the filename of an image
|
|
^ Position and size units are inventory slots
|
|
|
|
item_image_button[<X>,<Y>;<W>,<H>;<item name>;<name>;<label>]
|
|
^ x, y, w, h, name and label work as per button
|
|
^ item name is the registered name of an item/node,
|
|
tooltip will be made out of its descritption
|
|
^ Position and size units are inventory slots
|
|
|
|
button_exit[<X>,<Y>;<W>,<H>;<name>;<label>]
|
|
^ When clicked, fields will be sent and the form will quit.
|
|
|
|
image_button_exit[<X>,<Y>;<W>,<H>;<texture name>;<name>;<label>]
|
|
^ When clicked, fields will be sent and the form will quit.
|
|
|
|
Inventory location:
|
|
|
|
- "context": Selected node metadata (deprecated: "current_name")
|
|
- "current_player": Player to whom the menu is shown
|
|
- "player:<name>": Any player
|
|
- "nodemeta:<X>,<Y>,<Z>": Any node metadata
|
|
- "detached:<name>": A detached inventory
|
|
|
|
Helper functions
|
|
-----------------
|
|
dump2(obj, name="_", dumped={})
|
|
^ Return object serialized as a string, handles reference loops
|
|
dump(obj, dumped={})
|
|
^ Return object serialized as a string
|
|
string:split(separator)
|
|
^ eg. string:split("a,b", ",") == {"a","b"}
|
|
string:trim()
|
|
^ eg. string.trim("\n \t\tfoo bar\t ") == "foo bar"
|
|
minetest.pos_to_string({x=X,y=Y,z=Z}) -> "(X,Y,Z)"
|
|
^ Convert position to a printable string
|
|
minetest.string_to_pos(string) -> position
|
|
|
|
minetest namespace reference
|
|
-----------------------------
|
|
minetest.get_current_modname() -> string
|
|
minetest.get_modpath(modname) -> eg. "/home/user/.minetest/usermods/modname"
|
|
^ Useful for loading additional .lua modules or static data from mod
|
|
minetest.get_modnames() -> list of installed mods
|
|
^ Return a list of installed mods, sorted alphabetically
|
|
minetest.get_worldpath() -> eg. "/home/user/.minetest/world"
|
|
^ Useful for storing custom data
|
|
minetest.is_singleplayer()
|
|
|
|
minetest.debug(line)
|
|
^ Always printed to stderr and logfile (print() is redirected here)
|
|
minetest.log(line)
|
|
minetest.log(loglevel, line)
|
|
^ loglevel one of "error", "action", "info", "verbose"
|
|
|
|
Registration functions: (Call these only at load time)
|
|
minetest.register_entity(name, prototype table)
|
|
minetest.register_abm(abm definition)
|
|
minetest.register_node(name, node definition)
|
|
minetest.register_tool(name, item definition)
|
|
minetest.register_craftitem(name, item definition)
|
|
minetest.register_alias(name, convert_to)
|
|
minetest.register_craft(recipe)
|
|
|
|
Global callback registration functions: (Call these only at load time)
|
|
minetest.register_globalstep(func(dtime))
|
|
^ Called every server step, usually interval of 0.05s
|
|
minetest.register_on_shutdown(func())
|
|
^ Called before server shutdown
|
|
^ WARNING: If the server terminates abnormally (i.e. crashes), the registered
|
|
callbacks WILL LIKELY NOT BE RUN. Data should be saved at
|
|
semi-frequent intervals as well as on server shutdown.
|
|
minetest.register_on_placenode(func(pos, newnode, placer, oldnode, itemstack))
|
|
^ Called when a node has been placed
|
|
^ If return true no item is taken from itemstack
|
|
^ Deprecated: Use on_construct or after_place_node in node definition instead
|
|
minetest.register_on_dignode(func(pos, oldnode, digger))
|
|
^ Called when a node has been dug.
|
|
^ Deprecated: Use on_destruct or after_dig_node in node definition instead
|
|
minetest.register_on_punchnode(func(pos, node, puncher))
|
|
^ Called when a node is punched
|
|
minetest.register_on_generated(func(minp, maxp, blockseed))
|
|
^ Called after generating a piece of world. Modifying nodes inside the area
|
|
is a bit faster than usually.
|
|
minetest.register_on_newplayer(func(ObjectRef))
|
|
^ Called after a new player has been created
|
|
minetest.register_on_dieplayer(func(ObjectRef))
|
|
^ Called when a player dies
|
|
minetest.register_on_respawnplayer(func(ObjectRef))
|
|
^ Called when player is to be respawned
|
|
^ Called _before_ repositioning of player occurs
|
|
^ return true in func to disable regular player placement
|
|
minetest.register_on_joinplayer(func(ObjectRef))
|
|
^ Called when a player joins the game
|
|
minetest.register_on_leaveplayer(func(ObjectRef))
|
|
^ Called when a player leaves the game
|
|
minetest.register_on_chat_message(func(name, message))
|
|
^ Called always when a player says something
|
|
minetest.register_on_player_receive_fields(func(player, formname, fields))
|
|
^ Called when a button is pressed in player's inventory form
|
|
^ Newest functions are called first
|
|
^ If function returns true, remaining functions are not called
|
|
|
|
Other registration functions:
|
|
minetest.register_chatcommand(cmd, chatcommand definition)
|
|
minetest.register_privilege(name, definition)
|
|
^ definition: "description text"
|
|
^ definition: {
|
|
description = "description text",
|
|
give_to_singleplayer = boolean, -- default: true
|
|
}
|
|
minetest.register_authentication_handler(handler)
|
|
^ See minetest.builtin_auth_handler in builtin.lua for reference
|
|
|
|
Setting-related:
|
|
minetest.setting_set(name, value)
|
|
minetest.setting_get(name) -> string or nil
|
|
minetest.setting_getbool(name) -> boolean value or nil
|
|
minetest.setting_get_pos(name) -> position or nil
|
|
minetest.setting_save() -> nil, save all settings to config file
|
|
minetest.add_to_creative_inventory(itemstring)
|
|
|
|
Authentication:
|
|
minetest.notify_authentication_modified(name)
|
|
^ Should be called by the authentication handler if privileges change.
|
|
^ To report everybody, set name=nil.
|
|
minetest.get_password_hash(name, raw_password)
|
|
^ Convert a name-password pair to a password hash that minetest can use
|
|
minetest.string_to_privs(str) -> {priv1=true,...}
|
|
minetest.privs_to_string(privs) -> "priv1,priv2,..."
|
|
^ Convert between two privilege representations
|
|
minetest.set_player_password(name, password_hash)
|
|
minetest.set_player_privs(name, {priv1=true,...})
|
|
minetest.get_player_privs(name) -> {priv1=true,...}
|
|
minetest.auth_reload()
|
|
^ These call the authentication handler
|
|
minetest.check_player_privs(name, {priv1=true,...}) -> bool, missing_privs
|
|
^ A quickhand for checking privileges
|
|
|
|
Chat:
|
|
minetest.chat_send_all(text)
|
|
minetest.chat_send_player(name, text)
|
|
|
|
Inventory:
|
|
minetest.get_inventory(location) -> InvRef
|
|
^ location = eg. {type="player", name="celeron55"}
|
|
{type="node", pos={x=, y=, z=}}
|
|
{type="detached", name="creative"}
|
|
minetest.create_detached_inventory(name, callbacks) -> InvRef
|
|
^ callbacks: See "Detached inventory callbacks"
|
|
^ Creates a detached inventory. If it already exists, it is cleared.
|
|
minetest.show_formspec(playername, formname, formspec)
|
|
^ playername: name of player to show formspec
|
|
^ formname: name passed to on_player_receive_fields callbacks
|
|
^ should follow "modname:<whatever>" naming convention
|
|
^ formspec: formspec to display
|
|
|
|
Item handling:
|
|
minetest.inventorycube(img1, img2, img3)
|
|
^ Returns a string for making an image of a cube (useful as an item image)
|
|
minetest.get_pointed_thing_position(pointed_thing, above)
|
|
^ Get position of a pointed_thing (that you can get from somewhere)
|
|
minetest.dir_to_facedir(dir)
|
|
^ Convert a vector to a facedir value, used in param2 for paramtype2="facedir"
|
|
minetest.dir_to_wallmounted(dir)
|
|
^ Convert a vector to a wallmounted value, used for paramtype2="wallmounted"
|
|
minetest.get_node_drops(nodename, toolname)
|
|
^ Returns list of item names.
|
|
^ Note: This will be removed or modified in a future version.
|
|
minetest.get_craft_result(input) -> output, decremented_input
|
|
^ input.method = 'normal' or 'cooking' or 'fuel'
|
|
^ input.width = for example 3
|
|
^ input.items = for example { stack 1, stack 2, stack 3, stack 4,
|
|
stack 5, stack 6, stack 7, stack 8, stack 9 }
|
|
^ output.item = ItemStack, if unsuccessful: empty ItemStack
|
|
^ output.time = number, if unsuccessful: 0
|
|
^ decremented_input = like input
|
|
minetest.get_craft_recipe(output) -> input
|
|
^ output is a node or item type such as 'default:torch'
|
|
^ input.method = 'normal' or 'cooking' or 'fuel'
|
|
^ input.width = for example 3
|
|
^ input.items = for example { stack 1, stack 2, stack 3, stack 4,
|
|
stack 5, stack 6, stack 7, stack 8, stack 9 }
|
|
^ input.items = nil if no recipe found
|
|
minetest.handle_node_drops(pos, drops, digger)
|
|
^ drops: list of itemstrings
|
|
^ Handles drops from nodes after digging: Default action is to put them into
|
|
digger's inventory
|
|
^ Can be overridden to get different functionality (eg. dropping items on
|
|
ground)
|
|
|
|
Rollbacks:
|
|
minetest.rollback_get_last_node_actor(p, range, seconds) -> actor, p, seconds
|
|
^ Find who has done something to a node, or near a node
|
|
^ actor: "player:<name>", also "liquid".
|
|
minetest.rollback_revert_actions_by(actor, seconds) -> bool, log messages
|
|
^ Revert latest actions of someone
|
|
^ actor: "player:<name>", also "liquid".
|
|
|
|
Defaults for the on_* item definition functions:
|
|
(These return the leftover itemstack)
|
|
minetest.item_place_node(itemstack, placer, pointed_thing)
|
|
^ Place item as a node
|
|
minetest.item_place_object(itemstack, placer, pointed_thing)
|
|
^ Place item as-is
|
|
minetest.item_place(itemstack, placer, pointed_thing)
|
|
^ Use one of the above based on what the item is.
|
|
^ Calls on_rightclick of pointed_thing.under if defined instead
|
|
^ Note: is not called when wielded item overrides on_place
|
|
minetest.item_drop(itemstack, dropper, pos)
|
|
^ Drop the item
|
|
minetest.item_eat(hp_change, replace_with_item)
|
|
^ Eat the item. replace_with_item can be nil.
|
|
|
|
Defaults for the on_punch and on_dig node definition callbacks:
|
|
minetest.node_punch(pos, node, puncher)
|
|
^ Calls functions registered by minetest.register_on_punchnode()
|
|
minetest.node_dig(pos, node, digger)
|
|
^ Checks if node can be dug, puts item into inventory, removes node
|
|
^ Calls functions registered by minetest.registered_on_dignodes()
|
|
|
|
Sounds:
|
|
minetest.sound_play(spec, parameters) -> handle
|
|
^ spec = SimpleSoundSpec
|
|
^ parameters = sound parameter table
|
|
minetest.sound_stop(handle)
|
|
|
|
Timing:
|
|
minetest.after(time, func, param)
|
|
^ Call function after time seconds
|
|
^ param is optional; to pass multiple parameters, pass a table.
|
|
|
|
Server:
|
|
minetest.request_shutdown() -> request for server shutdown
|
|
minetest.get_server_status() -> server status string
|
|
|
|
Bans:
|
|
minetest.get_ban_list() -> ban list (same as minetest.get_ban_description(""))
|
|
minetest.get_ban_description(ip_or_name) -> ban description (string)
|
|
minetest.ban_player(name) -> ban a player
|
|
minetest.unban_player_or_ip(name) -> unban player or IP address
|
|
|
|
Random:
|
|
minetest.get_connected_players() -> list of ObjectRefs
|
|
minetest.hash_node_position({x=,y=,z=}) -> 48-bit integer
|
|
^ Gives a unique hash number for a node position (16+16+16=48bit)
|
|
minetest.get_item_group(name, group) -> rating
|
|
^ Get rating of a group of an item. (0 = not in group)
|
|
minetest.get_node_group(name, group) -> rating
|
|
^ Deprecated: An alias for the former.
|
|
minetest.serialize(table) -> string
|
|
^ Convert a table containing tables, strings, numbers, booleans and nils
|
|
into string form readable by minetest.deserialize
|
|
^ Example: serialize({foo='bar'}) -> 'return { ["foo"] = "bar" }'
|
|
minetest.deserialize(string) -> table
|
|
^ Convert a string returned by minetest.deserialize into a table
|
|
^ String is loaded in an empty sandbox environment.
|
|
^ Will load functions, but they cannot access the global environment.
|
|
^ Example: deserialize('return { ["foo"] = "bar" }') -> {foo='bar'}
|
|
^ Example: deserialize('print("foo")') -> nil (function call fails)
|
|
^ error:[string "print("foo")"]:1: attempt to call global 'print' (a nil value)
|
|
|
|
Global objects:
|
|
minetest.env - EnvRef of the server environment and world.
|
|
^ Using this you can access nodes and entities
|
|
|
|
Global tables:
|
|
minetest.registered_items
|
|
^ List of registered items, indexed by name
|
|
minetest.registered_nodes
|
|
^ List of registered node definitions, indexed by name
|
|
minetest.registered_craftitems
|
|
^ List of registered craft item definitions, indexed by name
|
|
minetest.registered_tools
|
|
^ List of registered tool definitions, indexed by name
|
|
minetest.registered_entities
|
|
^ List of registered entity prototypes, indexed by name
|
|
minetest.object_refs
|
|
^ List of object references, indexed by active object id
|
|
minetest.luaentities
|
|
^ List of lua entities, indexed by active object id
|
|
|
|
Deprecated but defined for backwards compatibility:
|
|
minetest.digprop_constanttime(time)
|
|
minetest.digprop_stonelike(toughness)
|
|
minetest.digprop_dirtlike(toughness)
|
|
minetest.digprop_gravellike(toughness)
|
|
minetest.digprop_woodlike(toughness)
|
|
minetest.digprop_leaveslike(toughness)
|
|
minetest.digprop_glasslike(toughness)
|
|
|
|
Class reference
|
|
----------------
|
|
EnvRef: basically ServerEnvironment and ServerMap combined.
|
|
methods:
|
|
- set_node(pos, node)
|
|
- add_node(pos, node): alias set_node(pos, node)
|
|
^ Set node at position (node = {name="foo", param1=0, param2=0})
|
|
- remove_node(pos)
|
|
^ Equivalent to set_node(pos, "air")
|
|
- get_node(pos)
|
|
^ Returns {name="ignore", ...} for unloaded area
|
|
- get_node_or_nil(pos)
|
|
^ Returns nil for unloaded area
|
|
- get_node_light(pos, timeofday) -> 0...15 or nil
|
|
^ timeofday: nil = current time, 0 = night, 0.5 = day
|
|
|
|
- place_node(pos, node)
|
|
^ Place node with the same effects that a player would cause
|
|
- dig_node(pos)
|
|
^ Dig node with the same effects that a player would cause
|
|
- punch_node(pos)
|
|
^ Punch node with the same effects that a player would cause
|
|
|
|
- get_meta(pos) -- Get a NodeMetaRef at that position
|
|
- get_node_timer(pos) -- Get NodeTimerRef
|
|
|
|
- add_entity(pos, name): Spawn Lua-defined entity at position
|
|
^ Returns ObjectRef, or nil if failed
|
|
- add_item(pos, item): Spawn item
|
|
^ Returns ObjectRef, or nil if failed
|
|
- get_player_by_name(name) -- Get an ObjectRef to a player
|
|
- get_objects_inside_radius(pos, radius)
|
|
- set_timeofday(val): val: 0...1; 0 = midnight, 0.5 = midday
|
|
- get_timeofday()
|
|
- find_node_near(pos, radius, nodenames) -> pos or nil
|
|
^ nodenames: eg. {"ignore", "group:tree"} or "default:dirt"
|
|
- find_nodes_in_area(minp, maxp, nodenames) -> list of positions
|
|
^ nodenames: eg. {"ignore", "group:tree"} or "default:dirt"
|
|
- get_perlin(seeddiff, octaves, persistence, scale)
|
|
^ Return world-specific perlin noise (int(worldseed)+seeddiff)
|
|
- clear_objects()
|
|
^ clear all objects in the environments
|
|
- spawn_tree (pos, {treedef})
|
|
^ spawns L-System tree at given pos with definition in treedef table
|
|
treedef={
|
|
axiom, - string initial tree axiom
|
|
rules_a, - string rules set A
|
|
rules_b, - string rules set B
|
|
rules_c, - string rules set C
|
|
rules_d, - string rules set D
|
|
trunk, - string trunk node name
|
|
leaves, - string leaves node name
|
|
leaves2, - string secondary leaves node name
|
|
leaves2_chance,- num chance (0-100) to replace leaves with leaves2
|
|
angle, - num angle in deg
|
|
iterations, - num max # of iterations, usually 2 -5
|
|
random_level, - num factor to lower nr of iterations, usually 0 - 3
|
|
trunk_type, - string single/double/crossed) type of trunk: 1 node, 2x2 nodes or 3x3 in cross shape
|
|
thin_branches, - boolean true -> use thin (1 node) branches
|
|
fruit, - string fruit node name
|
|
fruit_chance, - num chance (0-100) to replace leaves with fruit node
|
|
}
|
|
|
|
Key for Special L-System Symbols used in Axioms
|
|
G - move forward one unit with the pen up
|
|
F - move forward one unit with the pen down drawing trunks and branches
|
|
f - move forward one unit with the pen down drawing leaves (100% chance)
|
|
T - move forward one unit with the pen down drawing trunks only
|
|
R - move forward one unit with the pen down placing fruit
|
|
A - replace with rules set A
|
|
B - replace with rules set B
|
|
C - replace with rules set C
|
|
D - replace with rules set D
|
|
a - replace with rules set A, chance 90%
|
|
b - replace with rules set B, chance 80%
|
|
c - replace with rules set C, chance 70%
|
|
d - replace with rules set D, chance 60%
|
|
+ - yaw the turtle right by angle parameter
|
|
- - yaw the turtle left by angle parameter
|
|
& - pitch the turtle down by angle parameter
|
|
^ - pitch the turtle up by angle parameter
|
|
/ - roll the turtle to the right by angle parameter
|
|
* - roll the turtle to the left by angle parameter
|
|
[ - save in stack current state info
|
|
] - recover from stack state info
|
|
|
|
Example usage: spawn small apple tree
|
|
apple_tree={
|
|
axiom="FFFFFAFFBF",
|
|
rules_a="[&&&FFFFF&&FFFF][&&&++++FFFFF&&FFFF][&&&----FFFFF&&FFFF]",
|
|
rules_b="[&&&++FFFFF&&FFFF][&&&--FFFFF&&FFFF][&&&------FFFFF&&FFFF]",
|
|
trunk="default:tree",
|
|
leaves="default:leaves",
|
|
angle=30,
|
|
iterations=2,
|
|
random_level=0,
|
|
trunk_type="single",
|
|
thin_branches=true,
|
|
fruit_chance=10,
|
|
fruit="default:apple"
|
|
}
|
|
minetest.env:spawn_tree(pos,apple_tree)
|
|
|
|
Deprecated:
|
|
- add_rat(pos): Add C++ rat object (no-op)
|
|
- add_firefly(pos): Add C++ firefly object (no-op)
|
|
|
|
NodeMetaRef: Node metadata - reference extra data and functionality stored
|
|
in a node
|
|
- Can be gotten via minetest.env:get_nodemeta(pos)
|
|
methods:
|
|
- set_string(name, value)
|
|
- get_string(name)
|
|
- set_int(name, value)
|
|
- get_int(name)
|
|
- set_float(name, value)
|
|
- get_float(name)
|
|
- get_inventory() -> InvRef
|
|
- to_table() -> nil or {fields = {...}, inventory = {list1 = {}, ...}}
|
|
- from_table(nil or {})
|
|
^ See "Node Metadata"
|
|
|
|
NodeTimerRef: Node Timers - a high resolution persistent per-node timer
|
|
- Can be gotten via minetest.env:get_node_timer(pos)
|
|
methods:
|
|
- set(timeout,elapsed)
|
|
^ set a timer's state
|
|
^ timeout is in seconds, and supports fractional values (0.1 etc)
|
|
^ elapsed is in seconds, and supports fractional values (0.1 etc)
|
|
^ will trigger the node's on_timer function after timeout-elapsed seconds
|
|
- start(timeout)
|
|
^ start a timer
|
|
^ equivelent to set(timeout,0)
|
|
- stop()
|
|
^ stops the timer
|
|
- get_timeout() -> current timeout in seconds
|
|
^ if timeout is 0, timer is inactive
|
|
- get_elapsed() -> current elapsed time in seconds
|
|
^ the node's on_timer function will be called after timeout-elapsed seconds
|
|
- is_started() -> boolean state of timer
|
|
^ returns true if timer is started, otherwise false
|
|
|
|
ObjectRef: Moving things in the game are generally these
|
|
(basically reference to a C++ ServerActiveObject)
|
|
methods:
|
|
- remove(): remove object (after returning from Lua)
|
|
- getpos() -> {x=num, y=num, z=num}
|
|
- setpos(pos); pos={x=num, y=num, z=num}
|
|
- moveto(pos, continuous=false): interpolated move
|
|
- punch(puncher, time_from_last_punch, tool_capabilities, direction)
|
|
^ puncher = an another ObjectRef,
|
|
^ time_from_last_punch = time since last punch action of the puncher
|
|
^ direction: can be nil
|
|
- right_click(clicker); clicker = an another ObjectRef
|
|
- get_hp(): returns number of hitpoints (2 * number of hearts)
|
|
- set_hp(hp): set number of hitpoints (2 * number of hearts)
|
|
- get_inventory() -> InvRef
|
|
- get_wield_list(): returns the name of the inventory list the wielded item is in
|
|
- get_wield_index(): returns the index of the wielded item
|
|
- get_wielded_item() -> ItemStack
|
|
- set_wielded_item(item): replaces the wielded item, returns true if successful
|
|
- set_armor_groups({group1=rating, group2=rating, ...})
|
|
- set_animation({x=1,y=1}, frame_speed=15, frame_blend=0)
|
|
- set_attach(parent, "", {x=0,y=0,z=0}, {x=0,y=0,z=0})
|
|
- set_detach()
|
|
- set_bone_position("", {x=0,y=0,z=0}, {x=0,y=0,z=0})
|
|
- set_properties(object property table)
|
|
LuaEntitySAO-only: (no-op for other objects)
|
|
- setvelocity({x=num, y=num, z=num})
|
|
- getvelocity() -> {x=num, y=num, z=num}
|
|
- setacceleration({x=num, y=num, z=num})
|
|
- getacceleration() -> {x=num, y=num, z=num}
|
|
- setyaw(radians)
|
|
- getyaw() -> radians
|
|
- settexturemod(mod)
|
|
- setsprite(p={x=0,y=0}, num_frames=1, framelength=0.2,
|
|
- select_horiz_by_yawpitch=false)
|
|
^ Select sprite from spritesheet with optional animation and DM-style
|
|
texture selection based on yaw relative to camera
|
|
- get_entity_name() (DEPRECATED: Will be removed in a future version)
|
|
- get_luaentity()
|
|
Player-only: (no-op for other objects)
|
|
- is_player(): true for players, false for others
|
|
- get_player_name(): returns "" if is not a player
|
|
- get_look_dir(): get camera direction as a unit vector
|
|
- get_look_pitch(): pitch in radians
|
|
- get_look_yaw(): yaw in radians (wraps around pretty randomly as of now)
|
|
- set_inventory_formspec(formspec)
|
|
^ Redefine player's inventory form
|
|
^ Should usually be called in on_joinplayer
|
|
- get_inventory_formspec() -> formspec string
|
|
- get_player_control(): returns table with player pressed keys
|
|
{jump=bool,right=bool,left=bool,LMB=bool,RMB=bool,sneak=bool,aux1=bool,down=bool,up=bool}
|
|
- get_player_control_bits(): returns integer with bit packed player pressed keys
|
|
bit nr/meaning: 0/up ,1/down ,2/left ,3/right ,4/jump ,5/aux1 ,6/sneak ,7/LMB ,8/RMB
|
|
|
|
InvRef: Reference to an inventory
|
|
methods:
|
|
- is_empty(listname): return true if list is empty
|
|
- get_size(listname): get size of a list
|
|
- set_size(listname, size): set size of a list
|
|
- get_width(listname): get width of a list
|
|
- set_width(listname, width): set width of list; currently used for crafting
|
|
- get_stack(listname, i): get a copy of stack index i in list
|
|
- set_stack(listname, i, stack): copy stack to index i in list
|
|
- get_list(listname): return full list
|
|
- set_list(listname, list): set full list (size will not change)
|
|
- add_item(listname, stack): add item somewhere in list, returns leftover ItemStack
|
|
- room_for_item(listname, stack): returns true if the stack of items
|
|
can be fully added to the list
|
|
- contains_item(listname, stack): returns true if the stack of items
|
|
can be fully taken from the list
|
|
remove_item(listname, stack): take as many items as specified from the list,
|
|
returns the items that were actually removed (as an ItemStack)
|
|
- get_location() -> location compatible to minetest.get_inventory(location)
|
|
-> {type="undefined"} in case location is not known
|
|
|
|
ItemStack: A stack of items.
|
|
- Can be created via ItemStack(itemstack or itemstring or table or nil)
|
|
methods:
|
|
- is_empty(): return true if stack is empty
|
|
- get_name(): returns item name (e.g. "default:stone")
|
|
- get_count(): returns number of items on the stack
|
|
- get_wear(): returns tool wear (0-65535), 0 for non-tools
|
|
- get_metadata(): returns metadata (a string attached to an item stack)
|
|
- clear(): removes all items from the stack, making it empty
|
|
- replace(item): replace the contents of this stack (item can also
|
|
be an itemstring or table)
|
|
- to_string(): returns the stack in itemstring form
|
|
- to_table(): returns the stack in Lua table form
|
|
- get_stack_max(): returns the maximum size of the stack (depends on the item)
|
|
- get_free_space(): returns get_stack_max() - get_count()
|
|
- is_known(): returns true if the item name refers to a defined item type
|
|
- get_definition(): returns the item definition table
|
|
- get_tool_capabilities(): returns the digging properties of the item,
|
|
^ or those of the hand if none are defined for this item type
|
|
- add_wear(amount): increases wear by amount if the item is a tool
|
|
- add_item(item): put some item or stack onto this stack,
|
|
^ returns leftover ItemStack
|
|
- item_fits(item): returns true if item or stack can be fully added to this one
|
|
- take_item(n): take (and remove) up to n items from this stack
|
|
^ returns taken ItemStack
|
|
^ if n is omitted, n=1 is used
|
|
- peek_item(n): copy (don't remove) up to n items from this stack
|
|
^ returns copied ItemStack
|
|
^ if n is omitted, n=1 is used
|
|
|
|
PseudoRandom: A pseudorandom number generator
|
|
- Can be created via PseudoRandom(seed)
|
|
methods:
|
|
- next(): return next integer random number [0...32767]
|
|
- next(min, max): return next integer random number [min...max]
|
|
(max - min) must be 32767 or <= 6553 due to the simple
|
|
implementation making bad distribution otherwise.
|
|
|
|
PerlinNoise: A perlin noise generator
|
|
- Can be created via PerlinNoise(seed, octaves, persistence, scale)
|
|
- Also minetest.env:get_perlin(seeddiff, octaves, persistence, scale)
|
|
methods:
|
|
- get2d(pos) -> 2d noise value at pos={x=,y=}
|
|
- get3d(pos) -> 3d noise value at pos={x=,y=,z=}
|
|
|
|
Registered entities
|
|
--------------------
|
|
- Functions receive a "luaentity" as self:
|
|
- It has the member .name, which is the registered name ("mod:thing")
|
|
- It has the member .object, which is an ObjectRef pointing to the object
|
|
- The original prototype stuff is visible directly via a metatable
|
|
- Callbacks:
|
|
- on_activate(self, staticdata)
|
|
^ Called when the object is instantiated.
|
|
- on_step(self, dtime)
|
|
^ Called on every server tick (dtime is usually 0.05 seconds)
|
|
- on_punch(self, puncher, time_from_last_punch, tool_capabilities, dir)
|
|
^ Called when somebody punches the object.
|
|
^ Note that you probably want to handle most punches using the
|
|
automatic armor group system.
|
|
^ puncher: ObjectRef (can be nil)
|
|
^ time_from_last_punch: Meant for disallowing spamming of clicks (can be nil)
|
|
^ tool_capabilities: capability table of used tool (can be nil)
|
|
^ dir: unit vector of direction of punch. Always defined. Points from
|
|
the puncher to the punched.
|
|
- on_rightclick(self, clicker)
|
|
- get_staticdata(self)
|
|
^ Should return a string that will be passed to on_activate when
|
|
the object is instantiated the next time.
|
|
|
|
Definition tables
|
|
------------------
|
|
|
|
Object Properties
|
|
{
|
|
hp_max = 1,
|
|
physical = true,
|
|
weight = 5,
|
|
collisionbox = {-0.5,-0.5,-0.5, 0.5,0.5,0.5},
|
|
visual = "cube"/"sprite"/"upright_sprite"/"mesh",
|
|
visual_size = {x=1, y=1},
|
|
mesh = "model",
|
|
textures = {}, -- number of required textures depends on visual
|
|
colors = {}, -- number of required colors depends on visual
|
|
spritediv = {x=1, y=1},
|
|
initial_sprite_basepos = {x=0, y=0},
|
|
is_visible = true,
|
|
makes_footstep_sound = false,
|
|
automatic_rotate = false,
|
|
}
|
|
|
|
Entity definition (register_entity)
|
|
{
|
|
(Deprecated: Everything in object properties is read directly from here)
|
|
|
|
initial_properties = <initial object properties>,
|
|
|
|
on_activate = function(self, staticdata, dtime_s),
|
|
on_step = function(self, dtime),
|
|
on_punch = function(self, hitter),
|
|
on_rightclick = function(self, clicker),
|
|
get_staticdata = function(self),
|
|
^ Called sometimes; the string returned is passed to on_activate when
|
|
the entity is re-activated from static state
|
|
|
|
# Also you can define arbitrary member variables here
|
|
myvariable = whatever,
|
|
}
|
|
|
|
ABM (ActiveBlockModifier) definition (register_abm)
|
|
{
|
|
-- In the following two fields, also group:groupname will work.
|
|
nodenames = {"default:lava_source"},
|
|
neighbors = {"default:water_source", "default:water_flowing"}, -- (any of these)
|
|
^ If left out or empty, any neighbor will do
|
|
interval = 1.0, -- (operation interval)
|
|
chance = 1, -- (chance of trigger is 1.0/this)
|
|
action = func(pos, node, active_object_count, active_object_count_wider),
|
|
}
|
|
|
|
Item definition (register_node, register_craftitem, register_tool)
|
|
{
|
|
description = "Steel Axe",
|
|
groups = {}, -- key=name, value=rating; rating=1..3.
|
|
if rating not applicable, use 1.
|
|
eg. {wool=1, fluffy=3}
|
|
{soil=2, outerspace=1, crumbly=1}
|
|
{bendy=2, snappy=1},
|
|
{hard=1, metal=1, spikes=1}
|
|
inventory_image = "default_tool_steelaxe.png",
|
|
wield_image = "",
|
|
wield_scale = {x=1,y=1,z=1},
|
|
stack_max = 99,
|
|
liquids_pointable = false,
|
|
tool_capabilities = {
|
|
full_punch_interval = 1.0,
|
|
max_drop_level=0,
|
|
groupcaps={
|
|
-- For example:
|
|
fleshy={times={[2]=0.80, [3]=0.40}, maxwear=0.05, maxlevel=1},
|
|
snappy={times={[2]=0.80, [3]=0.40}, maxwear=0.05, maxlevel=1},
|
|
choppy={times={[3]=0.90}, maxwear=0.05, maxlevel=0}
|
|
}
|
|
}
|
|
node_placement_prediction = nil,
|
|
^ If nil and item is node, prediction is made automatically
|
|
^ If nil and item is not a node, no prediction is made
|
|
^ If "" and item is anything, no prediction is made
|
|
^ Otherwise should be name of node which the client immediately places
|
|
on ground when the player places the item. Server will always update
|
|
actual result to client in a short moment.
|
|
|
|
on_place = func(itemstack, placer, pointed_thing),
|
|
^ Shall place item and return the leftover itemstack
|
|
^ default: minetest.item_place
|
|
on_drop = func(itemstack, dropper, pos),
|
|
^ Shall drop item and return the leftover itemstack
|
|
^ default: minetest.item_drop
|
|
on_use = func(itemstack, user, pointed_thing),
|
|
^ default: nil
|
|
^ Function must return either nil if no item shall be removed from
|
|
inventory, or an itemstack to replace the original itemstack.
|
|
eg. itemstack:take_item(); return itemstack
|
|
^ Otherwise, the function is free to do what it wants.
|
|
^ The default functions handle regular use cases.
|
|
}
|
|
|
|
Tile definition:
|
|
- "image.png"
|
|
- {name="image.png", animation={Tile Animation definition}}
|
|
- {name="image.png", backface_culling=bool}
|
|
^ backface culling only supported in special tiles
|
|
- deprecated still supported field names:
|
|
- image -> name
|
|
|
|
Tile animation definition:
|
|
- {type="vertical_frames", aspect_w=16, aspect_h=16, length=3.0}
|
|
|
|
Node definition (register_node)
|
|
{
|
|
<all fields allowed in item definitions>,
|
|
|
|
drawtype = "normal", -- See "Node drawtypes"
|
|
visual_scale = 1.0,
|
|
tiles = {tile definition 1, def2, def3, def4, def5, def6},
|
|
^ Textures of node; +Y, -Y, +X, -X, +Z, -Z (old field name: tile_images)
|
|
^ List can be shortened to needed length
|
|
special_tiles = {tile definition 1, Tile definition 2},
|
|
^ Special textures of node; used rarely (old field name: special_materials)
|
|
^ List can be shortened to needed length
|
|
alpha = 255,
|
|
post_effect_color = {a=0, r=0, g=0, b=0}, -- If player is inside node
|
|
paramtype = "none", -- See "Nodes"
|
|
paramtype2 = "none", -- See "Nodes"
|
|
is_ground_content = false, -- Currently not used for anything
|
|
sunlight_propagates = false, -- If true, sunlight will go infinitely through this
|
|
walkable = true, -- If true, objects collide with node
|
|
pointable = true, -- If true, can be pointed at
|
|
diggable = true, -- If false, can never be dug
|
|
climbable = false, -- If true, can be climbed on (ladder)
|
|
buildable_to = false, -- If true, placed nodes can replace this node
|
|
drop = "", -- alternatively drop = { max_items = ..., items = { ... } }
|
|
liquidtype = "none", -- "none"/"source"/"flowing"
|
|
liquid_alternative_flowing = "", -- Flowing version of source liquid
|
|
liquid_alternative_source = "", -- Source version of flowing liquid
|
|
liquid_viscosity = 0, -- Higher viscosity = slower flow (max. 7)
|
|
liquid_renewable = true, -- Can new liquid source be created by placing
|
|
two or more sources nearly?
|
|
light_source = 0, -- Amount of light emitted by node
|
|
damage_per_second = 0, -- If player is inside node, this damage is caused
|
|
node_box = {type="regular"}, -- See "Node boxes"
|
|
selection_box = {type="regular"}, -- See "Node boxes"
|
|
legacy_facedir_simple = false, -- Support maps made in and before January 2012
|
|
legacy_wallmounted = false, -- Support maps made in and before January 2012
|
|
sounds = {
|
|
footstep = <SimpleSoundSpec>,
|
|
dig = <SimpleSoundSpec>, -- "__group" = group-based sound (default)
|
|
dug = <SimpleSoundSpec>,
|
|
},
|
|
|
|
on_construct = func(pos),
|
|
^ Node constructor; always called after adding node
|
|
^ Can set up metadata and stuff like that
|
|
^ default: nil
|
|
on_destruct = func(pos),
|
|
^ Node destructor; always called before removing node
|
|
^ default: nil
|
|
after_destruct = func(pos, oldnode),
|
|
^ Node destructor; always called after removing node
|
|
^ default: nil
|
|
|
|
after_place_node = func(pos, placer, itemstack),
|
|
^ Called after constructing node when node was placed using
|
|
minetest.item_place_node / minetest.env:place_node
|
|
^ If return true no item is taken from itemstack
|
|
^ default: nil
|
|
after_dig_node = func(pos, oldnode, oldmetadata, digger),
|
|
^ oldmetadata is in table format
|
|
^ Called after destructing node when node was dug using
|
|
minetest.node_dig / minetest.env:dig_node
|
|
^ default: nil
|
|
can_dig = function(pos,player)
|
|
^ returns true if node can be dug, or false if not
|
|
^ default: nil
|
|
|
|
on_punch = func(pos, node, puncher),
|
|
^ default: minetest.node_punch
|
|
^ By default: does nothing
|
|
on_rightclick = func(pos, node, clicker),
|
|
^ default: nil
|
|
on_dig = func(pos, node, digger),
|
|
^ default: minetest.node_dig
|
|
^ By default: checks privileges, wears out tool and removes node
|
|
|
|
on_timer = function(pos,elapsed),
|
|
^ default: nil
|
|
^ called by NodeTimers, see EnvRef and NodeTimerRef
|
|
^ elapsed is the total time passed since the timer was started
|
|
^ return true to run the timer for another cycle with the same timeout value
|
|
|
|
on_receive_fields = func(pos, formname, fields, sender),
|
|
^ fields = {name1 = value1, name2 = value2, ...}
|
|
^ Called when an UI form (eg. sign text input) returns data
|
|
^ default: nil
|
|
|
|
allow_metadata_inventory_move = func(pos, from_list, from_index,
|
|
to_list, to_index, count, player),
|
|
^ Called when a player wants to move items inside the inventory
|
|
^ Return value: number of items allowed to move
|
|
|
|
allow_metadata_inventory_put = func(pos, listname, index, stack, player),
|
|
^ Called when a player wants to put something into the inventory
|
|
^ Return value: number of items allowed to put
|
|
^ Return value: -1: Allow and don't modify item count in inventory
|
|
|
|
allow_metadata_inventory_take = func(pos, listname, index, stack, player),
|
|
^ Called when a player wants to take something out of the inventory
|
|
^ Return value: number of items allowed to take
|
|
^ Return value: -1: Allow and don't modify item count in inventory
|
|
|
|
on_metadata_inventory_move = func(pos, from_list, from_index,
|
|
to_list, to_index, count, player),
|
|
on_metadata_inventory_put = func(pos, listname, index, stack, player),
|
|
on_metadata_inventory_take = func(pos, listname, index, stack, player),
|
|
^ Called after the actual action has happened, according to what was allowed.
|
|
^ No return value
|
|
|
|
on_blast = func(pos, intensity),
|
|
^ intensity: 1.0 = mid range of regular TNT
|
|
^ If defined, called when an explosion touches the node, instead of
|
|
removing the node
|
|
}
|
|
|
|
Recipe for register_craft: (shaped)
|
|
{
|
|
output = 'default:pick_stone',
|
|
recipe = {
|
|
{'default:cobble', 'default:cobble', 'default:cobble'},
|
|
{'', 'default:stick', ''},
|
|
{'', 'default:stick', ''}, -- Also groups; eg. 'group:crumbly'
|
|
},
|
|
replacements = <optional list of item pairs,
|
|
replace one input item with another item on crafting>
|
|
}
|
|
|
|
Recipe for register_craft (shapeless)
|
|
{
|
|
type = "shapeless",
|
|
output = 'mushrooms:mushroom_stew',
|
|
recipe = {
|
|
"mushrooms:bowl",
|
|
"mushrooms:mushroom_brown",
|
|
"mushrooms:mushroom_red",
|
|
},
|
|
replacements = <optional list of item pairs,
|
|
replace one input item with another item on crafting>
|
|
}
|
|
|
|
Recipe for register_craft (tool repair)
|
|
{
|
|
type = "toolrepair",
|
|
additional_wear = -0.02,
|
|
}
|
|
|
|
Recipe for register_craft (cooking)
|
|
{
|
|
type = "cooking",
|
|
output = "default:glass",
|
|
recipe = "default:sand",
|
|
cooktime = 3,
|
|
}
|
|
|
|
Recipe for register_craft (furnace fuel)
|
|
{
|
|
type = "fuel",
|
|
recipe = "default:leaves",
|
|
burntime = 1,
|
|
}
|
|
|
|
Chatcommand definition (register_chatcommand)
|
|
{
|
|
params = "<name> <privilege>", -- short parameter description
|
|
description = "Remove privilege from player", -- full description
|
|
privs = {privs=true}, -- require the "privs" privilege to run
|
|
func = function(name, param), -- called when command is run
|
|
}
|
|
|
|
Detached inventory callbacks
|
|
{
|
|
allow_move = func(inv, from_list, from_index, to_list, to_index, count, player),
|
|
^ Called when a player wants to move items inside the inventory
|
|
^ Return value: number of items allowed to move
|
|
|
|
allow_put = func(inv, listname, index, stack, player),
|
|
^ Called when a player wants to put something into the inventory
|
|
^ Return value: number of items allowed to put
|
|
^ Return value: -1: Allow and don't modify item count in inventory
|
|
|
|
allow_take = func(inv, listname, index, stack, player),
|
|
^ Called when a player wants to take something out of the inventory
|
|
^ Return value: number of items allowed to take
|
|
^ Return value: -1: Allow and don't modify item count in inventory
|
|
|
|
on_move = func(inv, from_list, from_index, to_list, to_index, count, player),
|
|
on_put = func(inv, listname, index, stack, player),
|
|
on_take = func(inv, listname, index, stack, player),
|
|
^ Called after the actual action has happened, according to what was allowed.
|
|
^ No return value
|
|
}
|
|
|