Class reference¶
Sorted alphabetically.
AreaStore
¶
AreaStore is a data structure to calculate intersections of 3D cuboid volumes
and points. The data
field (string) may be used to store and retrieve any
mod-relevant information to the specified area.
Despite its name, mods must take care of persisting AreaStore data. They may use the provided load and write functions for this.
Methods¶
AreaStore(type_name)
- Returns a new AreaStore instance
type_name
: optional, forces the internally used API.- Possible values:
"LibSpatial"
(default). - When other values are specified, or SpatialIndex is not available, the custom Minetest functions are used.
- Possible values:
-
get_area(id, include_corners, include_data)
- Returns the area information about the specified ID.
- Returned values are either of these:
nil -- Area not found true -- Without `include_corners` and `include_data` { min = pos, max = pos -- `include_corners == true` data = string -- `include_data == true` }
-
get_areas_for_pos(pos, include_corners, include_data)
- Returns all areas as table, indexed by the area ID.
- Table values: see
get_area
.
get_areas_in_area(corner1, corner2, accept_overlap, include_corners, include_data)
- Returns all areas that contain all nodes inside the area specified by
corner1 and
corner2
(inclusive). accept_overlap
: iftrue
, areas are returned that have nodes in common (intersect) with the specified area.- Returns the same values as
get_areas_for_pos
.
- Returns all areas that contain all nodes inside the area specified by
insert_area(corner1, corner2, data, [id])
: inserts an area into the store.- Returns the new area's ID, or nil if the insertion failed.
- The (inclusive) positions
corner1
andcorner2
describe the area. data
is a string stored with the area.id
(optional): will be used as the internal area ID if it is a unique number between 0 and 2^32-2.
reserve(count)
- Requires SpatialIndex, no-op function otherwise.
- Reserves resources for
count
many contained areas to improve efficiency when working with many area entries. Additional areas can still be inserted afterwards at the usual complexity.
remove_area(id)
: removes the area with the given id from the store, returns success.set_cache_params(params)
: sets params for the included prefiltering cache. Calling invalidates the cache, so that its elements have to be newly generated.-
params
is a table with the following fields:enabled = boolean, -- Whether to enable, default true block_radius = int, -- The radius (in nodes) of the areas the cache -- generates prefiltered lists for, minimum 16, -- default 64 limit = int, -- The cache size, minimum 20, default 1000 *
to_string()
: Experimental. Returns area store serialized as a (binary) string. *to_file(filename)
: Experimental. Liketo_string()
, but writes the data to a file. *from_string(str)
: Experimental. Deserializes string and loads it into the AreaStore. Returns success and, optionally, an error message. *from_file(filename)
: Experimental. Likefrom_string()
, but reads the data from a file.
-
InvRef
¶
An InvRef
is a reference to an inventory.
Methods¶
is_empty(listname)
: returntrue
if list is emptyget_size(listname)
: get size of a listset_size(listname, size)
: set size of a list- returns
false
on error (e.g. invalidlistname
orsize
)
- returns
get_width(listname)
: get width of a listset_width(listname, width)
: set width of list; currently used for craftingget_stack(listname, i)
: get a copy of stack indexi
in listset_stack(listname, i, stack)
: copystack
to indexi
in listget_list(listname)
: returns full list (list ofItemStack
s) ornil
if list doesn't exist (size 0)set_list(listname, list)
: set full list (size will not change)get_lists()
: returns table that maps listnames to inventory listsset_lists(lists)
: sets inventory lists (size will not change)add_item(listname, stack)
: add item somewhere in list, returns leftoverItemStack
.room_for_item(listname, stack):
returnstrue
if the stack of items can be fully added to the listcontains_item(listname, stack, [match_meta])
: returnstrue
if the stack of items can be fully taken from the list. Ifmatch_meta
is false, only the items' names are compared (default:false
).remove_item(listname, stack)
: take as many items as specified from the list, returns the items that were actually removed (as anItemStack
) -- note that any item metadata is ignored, so attempting to remove a specific unique item this way will likely remove the wrong one -- to do that useset_stack
with an emptyItemStack
.get_location()
: returns a location compatible tominetest.get_inventory(location)
.- returns
{type="undefined"}
in case location is not known
- returns
Callbacks¶
Detached & nodemeta inventories provide the following callbacks for move actions:
Before¶
The allow_*
callbacks return how many items can be moved.
allow_move
/allow_metadata_inventory_move
: Moving items in the inventoryallow_take
/allow_metadata_inventory_take
: Taking items from the inventoryallow_put
/allow_metadata_inventory_put
: Putting items to the inventory
After¶
The on_*
callbacks are called after the items have been placed in the inventories.
on_move
/on_metadata_inventory_move
: Moving items in the inventoryon_take
/on_metadata_inventory_take
: Taking items from the inventoryon_put
/on_metadata_inventory_put
: Putting items to the inventory
Swapping¶
When a player tries to put an item to a place where another item is, the items are swapped. This means that all callbacks will be called twice (once for each action).
ItemStack
¶
An ItemStack
is a stack of items.
It can be created via ItemStack(x)
, where x is an ItemStack
,
an itemstring, a table or nil
.
Methods¶
is_empty()
: returnstrue
if stack is empty.get_name()
: returns item name (e.g."default:stone"
).set_name(item_name)
: returns a boolean indicating whether the item was cleared.get_count()
: Returns number of items on the stack.set_count(count)
: returns a boolean indicating whether the item was clearedcount
: number, unsigned 16 bit integer
get_wear()
: returns tool wear (0
-65535
),0
for non-tools.set_wear(wear)
: returns boolean indicating whether item was clearedwear
: number, unsigned 16 bit integer
get_meta()
: returns ItemStackMetaRef. See section for more detailsget_metadata()
: (DEPRECATED) Returns metadata (a string attached to an item stack).set_metadata(metadata)
: (DEPRECATED) Returns true.get_description()
: returns the description shown in inventory list tooltips.- The engine uses this when showing item descriptions in tooltips.
- Fields for finding the description, in order:
description
in item metadata (See [Item Metadata].)description
in item definition- item name
get_short_description()
: returns the short description or nil.- Unlike the description, this does not include new lines.
- Fields for finding the short description, in order:
short_description
in item metadata (See [Item Metadata].)short_description
in item definition- first line of the description (From item meta or def, see
get_description()
.) - Returns nil if none of the above are set
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()
: returnsget_stack_max() - get_count()
.is_known()
: returnstrue
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 typeadd_wear(amount)
- Increases wear by
amount
if the item is a tool, otherwise does nothing - Valid
amount
range is [0,65536] amount
: number, integer
- Increases wear by
add_wear_by_uses(max_uses)
- Increases wear in such a way that, if only this function is called,
the item breaks after
max_uses
times - Valid
max_uses
range is [0,65536] - Does nothing if item is not a tool or if
max_uses
is 0
- Increases wear in such a way that, if only this function is called,
the item breaks after
add_item(item)
: returns leftoverItemStack
- Put some item or stack onto this stack
item_fits(item)
: returnstrue
if item or stack can be fully added to this one.take_item(n)
: returns takenItemStack
- Take (and remove) up to
n
items from this stack n
: number, default:1
- Take (and remove) up to
peek_item(n)
: returns takenItemStack
- Copy (don't remove) up to
n
items from this stack n
: number, default:1
- Copy (don't remove) up to
equals(other)
:- returns
true
if this stack is identical toother
. - Note:
stack1:to_string() == stack2:to_string()
is not reliable, as stack metadata can be serialized in arbitrary order. - Note: if
other
is an itemstring or table representation of an ItemStack, this will always return false, even if it is "equivalent".
- returns
Operators¶
stack1 == stack2
:- Returns whether
stack1
andstack2
are identical. - Note:
stack1:to_string() == stack2:to_string()
is not reliable, as stack metadata can be serialized in arbitrary order. - Note: if
stack2
is an itemstring or table representation of an ItemStack, this will always return false, even if it is "equivalent".
- Returns whether
ItemStackMetaRef
¶
ItemStack metadata: reference extra data and functionality stored in a stack.
Can be obtained via item:get_meta()
.
Methods¶
- All methods in MetaDataRef
set_tool_capabilities([tool_capabilities])
- Overrides the item's tool capabilities
- A nil value will clear the override data and restore the original behavior.
MetaDataRef
¶
Base class used by [StorageRef
], [NodeMetaRef
], [ItemStackMetaRef
],
and [PlayerMetaRef
].
Note: If a metadata value is in the format ${k}
, an attempt to get the value
will return the value associated with key k
. There is a low recursion limit.
This behavior is deprecated and will be removed in a future version. Usage
of the ${k}
syntax in formspecs is not deprecated.
Methods¶
contains(key)
: Returns true if key present, otherwise false.- Returns
nil
when the MetaData is inexistent.
- Returns
get(key)
: Returnsnil
if key not present, else the stored string.set_string(key, value)
: Value of""
will delete the key.get_string(key)
: Returns""
if key not present.set_int(key, value)
get_int(key)
: Returns0
if key not present.set_float(key, value)
get_float(key)
: Returns0
if key not present.get_keys()
: returns a list of all keys in the metadata.to_table()
:- Returns a metadata table (see below) or
nil
on failure.
- Returns a metadata table (see below) or
from_table(data)
- Imports metadata from a metadata table
- If
data
is a metadata table (see below), the metadata it represents will replace all metadata of this MetaDataRef object - Any non-table value for
data
will clear all metadata - Item table values the
inventory
field may also be itemstrings - Returns
true
on success
equals(other)
- returns
true
if this metadata has the same key-value pairs asother
- returns
Metadata tables¶
Metadata tables represent MetaDataRef in a Lua table form (see from_table
/to_table
).
A metadata table is a table that has the following keys:
fields
: key-value storage of metadata fields- all values are stored as strings
- numbers must be converted to strings first
inventory
(for NodeMetaRef only): A node inventory in table form- inventory table keys are inventory list names
- inventory table values are item tables
- item table keys are slot IDs (starting with 1)
- item table values are ItemStacks
Example:
metadata_table = {
-- metadata fields (key/value store)
fields = {
infotext = "Container",
anoter_key = "Another Value",
},
-- inventory data (for nodes)
inventory = {
-- inventory list "main" with 4 slots
main = {
-- list of all item slots
[1] = "example:dirt",
[2] = "example:stone 25",
[3] = "", -- empty slot
[4] = "example:pickaxe",
},
-- inventory list "hidden" with 1 slot
hidden = {
[1] = "example:diamond",
},
},
}
ModChannel
¶
An interface to use mod channels on client and server
Methods¶
leave()
: leave the mod channel.- Server leaves channel
channel_name
. - No more incoming or outgoing messages can be sent to this channel from server mods.
- This invalidate all future object usage.
- Ensure you set mod_channel to nil after that to free Lua resources.
- Server leaves channel
is_writeable()
: returns true if channel is writeable and mod can send over it.send_all(message)
: Sendmessage
though the mod channel.- If mod channel is not writeable or invalid, message will be dropped.
- Message size is limited to 65535 characters by protocol.
NodeMetaRef
¶
Node metadata: reference extra data and functionality stored in a node.
Can be obtained via minetest.get_meta(pos)
.
Methods¶
- All methods in MetaDataRef
get_inventory()
: returnsInvRef
mark_as_private(name or {name1, name2, ...})
: Mark specific vars as private This will prevent them from being sent to the client. Note that the "private" status will only be remembered if an associated key-value pair exists, meaning it's best to call this when initializing all other meta (e.g.on_construct
).
NodeTimerRef
¶
Node Timers: a high resolution persistent per-node timer.
Can be gotten via minetest.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
- equivalent to
set(timeout,0)
stop()
- stops the timer
get_timeout()
: returns current timeout in seconds- if
timeout
equals0
, timer is inactive
- if
get_elapsed()
: returns current elapsed time in seconds- the node's
on_timer
function will be called after(timeout - elapsed)
seconds.
- the node's
is_started()
: returns boolean state of timer- returns
true
if timer is started, otherwisefalse
- returns
ObjectRef
¶
Moving things in the game are generally these.
This is basically a reference to a C++ ServerActiveObject
.
Advice on handling ObjectRefs
¶
When you receive an ObjectRef
as a callback argument or from another API
function, it is possible to store the reference somewhere and keep it around.
It will keep functioning until the object is unloaded or removed.
However, doing this is NOT recommended as there is (intentionally) no method
to test if a previously acquired ObjectRef
is still valid.
Instead, ObjectRefs
should be "let go" of as soon as control is returned from
Lua back to the engine.
Doing so is much less error-prone and you will never need to wonder if the
object you are working with still exists.
Attachments¶
It is possible to attach objects to other objects (set_attach
method).
When an object is attached, it is positioned relative to the parent's position
and rotation. get_pos
and get_rotation
will always return the parent's
values and changes via their setter counterparts are ignored.
To change position or rotation call set_attach
again with the new values.
Note: Just like model dimensions, the relative position in set_attach
must be multiplied by 10 compared to world positions.
It is also possible to attach to a bone of the parent object. In that case the child will follow movement and rotation of that bone.
Methods¶
get_pos()
: returns{x=num, y=num, z=num}
set_pos(pos)
:pos
={x=num, y=num, z=num}
get_velocity()
: returns the velocity, a vector.add_velocity(vel)
vel
is a vector, e.g.{x=0.0, y=2.3, z=1.0}
- In comparison to using get_velocity, adding the velocity and then using set_velocity, add_velocity is supposed to avoid synchronization problems. Additionally, players also do not support set_velocity.
- If a player:
- Does not apply during free_move.
- Note that since the player speed is normalized at each move step, increasing e.g. Y velocity beyond what would usually be achieved (see: physics overrides) will cause existing X/Z velocity to be reduced.
- Example:
add_velocity({x=0, y=6.5, z=0})
is equivalent to pressing the jump key (assuming default settings)
move_to(pos, continuous=false)
- Does an interpolated move for Lua entities for visually smooth transitions.
- If
continuous
is true, the Lua entity will not be moved to the current position before starting the interpolated move. - For players this does the same as
set_pos
,continuous
is ignored.
punch(puncher, time_from_last_punch, tool_capabilities, direction)
puncher
= anotherObjectRef
,time_from_last_punch
= time since last punch action of the puncherdirection
: can benil
right_click(clicker)
;clicker
is anotherObjectRef
get_hp()
: returns number of health pointsset_hp(hp, reason)
: set number of health points- See reason in register_on_player_hpchange
- Is limited to the range of 0 ... 65535 (2^16 - 1)
- For players: HP are also limited by
hp_max
specified in object properties
get_inventory()
: returns anInvRef
for players, otherwise returnsnil
get_wield_list()
: returns the name of the inventory list the wielded item is in.get_wield_index()
: returns the index of the wielded itemget_wielded_item()
: returns anItemStack
set_wielded_item(item)
: replaces the wielded item, returnstrue
if successful.set_armor_groups({group1=rating, group2=rating, ...})
get_armor_groups()
: returns a table with the armor group ratingsset_animation(frame_range, frame_speed, frame_blend, frame_loop)
frame_range
: table {x=num, y=num}, default:{x=1, y=1}
frame_speed
: number, default:15.0
frame_blend
: number, default:0.0
frame_loop
: boolean, default:true
get_animation()
: returnsrange
,frame_speed
,frame_blend
andframe_loop
.set_animation_frame_speed(frame_speed)
frame_speed
: number, default:15.0
set_attach(parent[, bone, position, rotation, forced_visible])
parent
:ObjectRef
to attach tobone
: default""
(the root bone)position
: relative position, default{x=0, y=0, z=0}
rotation
: relative rotation in degrees, default{x=0, y=0, z=0}
forced_visible
: Boolean to control whether the attached entity should appear in first person, defaultfalse
.- Please also read the [Attachments] section above.
- This command may fail silently (do nothing) when it would result in circular attachments.
get_attach()
: returns parent, bone, position, rotation, forced_visible, or nil if it isn't attached.get_children()
: returns a list of ObjectRefs that are attached to the object.set_detach()
set_bone_position([bone, position, rotation])
bone
: string. Default is""
, the root boneposition
:{x=num, y=num, z=num}
, relative,default {x=0, y=0, z=0}
rotation
:{x=num, y=num, z=num}
, default{x=0, y=0, z=0}
get_bone_position(bone)
: returns position and rotation of the boneset_properties(object property table)
get_properties()
: returns object property tableis_player()
: returns true for players, false otherwiseget_nametag_attributes()
- returns a table with the attributes of the nametag of an object
- { text = "", color = {a=0..255, r=0..255, g=0..255, b=0..255}, bgcolor = {a=0..255, r=0..255, g=0..255, b=0..255}, }
set_nametag_attributes(attributes)
- sets the attributes of the nametag of an object
attributes
: { text = "My Nametag", color = ColorSpec, -- ^ Text color bgcolor = ColorSpec or false, -- ^ Sets background color of nametag --false
will cause the background to be set automatically based on user settings -- Default: false }
Lua entity only (no-op for other objects)¶
remove()
: remove object- The object is removed after returning from Lua. However the
ObjectRef
itself instantly becomes unusable with all further method calls having no effect and returningnil
.
- The object is removed after returning from Lua. However the
set_velocity(vel)
vel
is a vector, e.g.{x=0.0, y=2.3, z=1.0}
set_acceleration(acc)
acc
is a vector
get_acceleration()
: returns the acceleration, a vectorset_rotation(rot)
rot
is a vector (radians). X is pitch (elevation), Y is yaw (heading) and Z is roll (bank).- Does not reset rotation incurred through
automatic_rotate
. Remove & readd your objects to force a certain rotation.
get_rotation()
: returns the rotation, a vector (radians)set_yaw(yaw)
: sets the yaw in radians (heading).get_yaw()
: returns number in radiansset_texture_mod(mod)
- Set a texture modifier to the base texture, for sprites and meshes.
- When calling
set_texture_mod
again, the previous one is discarded. mod
the texture modifier. See [Texture modifiers].
get_texture_mod()
returns current texture modifierset_sprite(start_frame, num_frames, framelength, select_x_by_camera)
- Specifies and starts a sprite animation
- Animations iterate along the frame
y
position. start_frame
: {x=column number, y=row number}, the coordinate of the first frame, default:{x=0, y=0}
num_frames
: Total frames in the texture, default:1
framelength
: Time per animated frame in seconds, default:0.2
select_x_by_camera
: Only for visual =sprite
. Changes the framex
position according to the view direction. default:false
.- First column: subject facing the camera
- Second column: subject looking to the left
- Third column: subject backing the camera
- Fourth column: subject looking to the right
- Fifth column: subject viewed from above
- Sixth column: subject viewed from below
get_entity_name()
(Deprecated: Will be removed in a future version, use the fieldself.name
instead)get_luaentity()
Player only (no-op for other objects)¶
get_player_name()
: returns""
if is not a playerget_player_velocity()
: DEPRECATED, use get_velocity() instead. table {x, y, z} representing the player's instantaneous velocity in nodes/sadd_player_velocity(vel)
: DEPRECATED, use add_velocity(vel) instead.get_look_dir()
: get camera direction as a unit vectorget_look_vertical()
: pitch in radians- Angle ranges between -pi/2 and pi/2, which are straight up and down respectively.
get_look_horizontal()
: yaw in radians- Angle is counter-clockwise from the +z direction.
set_look_vertical(radians)
: sets look pitch- radians: Angle from looking forward, where positive is downwards.
set_look_horizontal(radians)
: sets look yaw- radians: Angle from the +z direction, where positive is counter-clockwise.
get_look_pitch()
: pitch in radians - Deprecated as broken. Useget_look_vertical
.- Angle ranges between -pi/2 and pi/2, which are straight down and up respectively.
get_look_yaw()
: yaw in radians - Deprecated as broken. Useget_look_horizontal
.- Angle is counter-clockwise from the +x direction.
set_look_pitch(radians)
: sets look pitch - Deprecated. Useset_look_vertical
.set_look_yaw(radians)
: sets look yaw - Deprecated. Useset_look_horizontal
.get_breath()
: returns player's breathset_breath(value)
: sets player's breath- values:
0
: player is drowning- max: bubbles bar is not shown
- See [Object properties] for more information
- Is limited to range 0 ... 65535 (2^16 - 1)
- values:
set_fov(fov, is_multiplier, transition_time)
: Sets player's FOVfov
: FOV value.is_multiplier
: Set totrue
if the FOV value is a multiplier. Defaults tofalse
.transition_time
: If defined, enables smooth FOV transition. Interpreted as the time (in seconds) to reach target FOV. If set to 0, FOV change is instantaneous. Defaults to 0.- Set
fov
to 0 to clear FOV override.
get_fov()
: Returns the following:- Server-sent FOV value. Returns 0 if an FOV override doesn't exist.
- Boolean indicating whether the FOV value is a multiplier.
- Time (in seconds) taken for the FOV transition. Set by
set_fov
.
set_attribute(attribute, value)
: DEPRECATED, use get_meta() instead- Sets an extra attribute with value on player.
value
must be a string, or a number which will be converted to a string.- If
value
isnil
, remove attribute from player.
get_attribute(attribute)
: DEPRECATED, use get_meta() instead- Returns value (a string) for extra attribute.
- Returns
nil
if no attribute found.
get_meta()
: Returns a PlayerMetaRef.set_inventory_formspec(formspec)
- Redefine player's inventory form
- Should usually be called in
on_joinplayer
- If
formspec
is""
, the player's inventory is disabled.
get_inventory_formspec()
: returns a formspec stringset_formspec_prepend(formspec)
:- the formspec string will be added to every formspec shown to the user, except for those with a no_prepend[] tag.
- This should be used to set style elements such as background[] and bgcolor[], any non-style elements (eg: label) may result in weird behavior.
- Only affects formspecs shown after this is called.
get_formspec_prepend()
: returns a formspec string.get_player_control()
: returns table with player pressed keys- The table consists of fields with the following boolean values
representing the pressed keys:
up
,down
,left
,right
,jump
,aux1
,sneak
,dig
,place
,LMB
,RMB
, andzoom
. - The fields
LMB
andRMB
are equal todig
andplace
respectively, and exist only to preserve backwards compatibility. - Returns an empty table
{}
if the object is not a player.
- The table consists of fields with the following boolean values
representing the pressed keys:
get_player_control_bits()
: returns integer with bit packed player pressed keys.- Bits:
- 0 - up
- 1 - down
- 2 - left
- 3 - right
- 4 - jump
- 5 - aux1
- 6 - sneak
- 7 - dig
- 8 - place
- 9 - zoom
- Returns
0
(no bits set) if the object is not a player.
- Bits:
set_physics_override(override_table)
override_table
is a table with the following fields:speed
: multiplier to default walking speed value (default:1
)jump
: multiplier to default jump value (default:1
)gravity
: multiplier to default gravity value (default:1
)sneak
: whether player can sneak (default:true
)sneak_glitch
: whether player can use the new move code replications of the old sneak side-effects: sneak ladders and 2 node sneak jump (default:false
)new_move
: use new move/sneak code. Whenfalse
the exact old code is used for the specific old sneak behavior (default:true
)
get_physics_override()
: returns the table given toset_physics_override
hud_add(hud definition)
: add a HUD element described by HUD def, returns ID number on successhud_remove(id)
: remove the HUD element of the specified idhud_change(id, stat, value)
: change a value of a previously added HUD element.stat
supports the same keys as in the hud definition table except for"hud_elem_type"
.
hud_get(id)
: gets the HUD element definition structure of the specified IDhud_set_flags(flags)
: sets specified HUD flags of player.flags
: A table with the following fields set to boolean valueshotbar
healthbar
crosshair
wielditem
breathbar
minimap
: Modifies the client's permission to view the minimap. The client may locally elect to not view the minimap.minimap_radar
: is only usable whenminimap
is truebasic_debug
: Allow showing basic debug info that might give a gameplay advantage. This includes map seed, player position, look direction, the pointed node and block bounds. Does not affect players with thedebug
privilege.chat
: Modifies the client's permission to view chat on the HUD. The client may locally elect to not view chat. Does not affect the console.
- If a flag equals
nil
, the flag is not modified
hud_get_flags()
: returns a table of player HUD flags with boolean values.- See
hud_set_flags
for a list of flags that can be toggled.
- See
hud_set_hotbar_itemcount(count)
: sets number of items in builtin hotbarcount
: number of items, must be between1
and32
hud_get_hotbar_itemcount()
: returns number of visible itemshud_set_hotbar_image(texturename)
- sets background image for hotbar
hud_get_hotbar_image()
: returns texturenamehud_set_hotbar_selected_image(texturename)
- sets image for selected item of hotbar
hud_get_hotbar_selected_image()
: returns texturenameset_minimap_modes({mode, mode, ...}, selected_mode)
- Overrides the available minimap modes (and toggle order), and changes the selected mode.
mode
is a table consisting of up to four fields:type
: Available type:off
: Minimap offsurface
: Minimap in surface moderadar
: Minimap in radar modetexture
: Texture to be displayed instead of terrain map (texture is centered around 0,0 and can be scaled). Texture size is limited to 512 x 512 pixel.
label
: Optional label to display on minimap mode toggle The translation must be handled within the mod.size
: Sidelength or diameter, in number of nodes, of the terrain displayed in minimaptexture
: Only for texture type, name of the texture to displayscale
: Only for texture type, scale of the texture map in nodes per pixel (for example ascale
of 2 means each pixel represents a 2x2 nodes square)
selected_mode
is the mode index to be selected after modes have been changed (0 is the first mode).
set_sky(sky_parameters)
- The presence of the function
set_sun
,set_moon
orset_stars
indicates whetherset_sky
accepts this format. Check the legacy format otherwise. - Passing no arguments resets the sky to its default values.
sky_parameters
is a table with the following optional fields:base_color
: ColorSpec, changes fog in "skybox" and "plain". (default:#ffffff
)body_orbit_tilt
: Float, rotation angle of sun/moon orbit in degrees. By default, orbit is controlled by a client-side setting, and this field is not set. After a value is assigned, it can only be changed to another float value. Valid range [-60.0,60.0] (default: not set)type
: Available types:"regular"
: Uses 0 textures,base_color
ignored"skybox"
: Uses 6 textures,base_color
used as fog."plain"
: Uses 0 textures,base_color
used as both fog and sky. (default:"regular"
)
textures
: A table containing up to six textures in the following order: Y+ (top), Y- (bottom), X- (west), X+ (east), Z+ (north), Z- (south).clouds
: Boolean for whether clouds appear. (default:true
)sky_color
: A table used in"regular"
type only, containing the following values (alpha is ignored):day_sky
: ColorSpec, for the top half of the sky during the day. (default:#61b5f5
)day_horizon
: ColorSpec, for the bottom half of the sky during the day. (default:#90d3f6
)dawn_sky
: ColorSpec, for the top half of the sky during dawn/sunset. (default:#b4bafa
) The resulting sky color will be a darkened version of the ColorSpec. Warning: The darkening of the ColorSpec is subject to change.dawn_horizon
: ColorSpec, for the bottom half of the sky during dawn/sunset. (default:#bac1f0
) The resulting sky color will be a darkened version of the ColorSpec. Warning: The darkening of the ColorSpec is subject to change.night_sky
: ColorSpec, for the top half of the sky during the night. (default:#006bff
) The resulting sky color will be a dark version of the ColorSpec. Warning: The darkening of the ColorSpec is subject to change.night_horizon
: ColorSpec, for the bottom half of the sky during the night. (default:#4090ff
) The resulting sky color will be a dark version of the ColorSpec. Warning: The darkening of the ColorSpec is subject to change.indoors
: ColorSpec, for when you're either indoors or underground. (default:#646464
)fog_sun_tint
: ColorSpec, changes the fog tinting for the sun at sunrise and sunset. (default:#f47d1d
)fog_moon_tint
: ColorSpec, changes the fog tinting for the moon at sunrise and sunset. (default:#7f99cc
)fog_tint_type
: string, changes which mode the directional fog abides by,"custom"
usessun_tint
andmoon_tint
, while"default"
uses the classic Minetest sun and moon tinting. Will use tonemaps, if set to"default"
. (default:"default"
)
- The presence of the function
set_sky(base_color, type, {texture names}, clouds)
- Deprecated. Use
set_sky(sky_parameters)
base_color
: ColorSpec, defaults to whitetype
: Available types:"regular"
: Uses 0 textures,bgcolor
ignored"skybox"
: Uses 6 textures,bgcolor
used"plain"
: Uses 0 textures,bgcolor
used
clouds
: Boolean for whether clouds appear in front of"skybox"
or"plain"
custom skyboxes (default:true
)
- Deprecated. Use
get_sky(as_table)
:as_table
: boolean that determines whether the deprecated version of this function is being used.true
returns a table containing sky parameters as defined inset_sky(sky_parameters)
.- Deprecated:
false
ornil
returns base_color, type, table of textures, clouds.
get_sky_color()
:- Deprecated: Use
get_sky(as_table)
instead. - returns a table with the
sky_color
parameters as inset_sky
.
- Deprecated: Use
set_sun(sun_parameters)
:- Passing no arguments resets the sun to its default values.
sun_parameters
is a table with the following optional fields:visible
: Boolean for whether the sun is visible. (default:true
)texture
: A regular texture for the sun. Setting to""
will re-enable the mesh sun. (default: "sun.png", if it exists) The texture appears non-rotated at sunrise and rotated 180 degrees (upside down) at sunset.tonemap
: A 512x1 texture containing the tonemap for the sun (default:"sun_tonemap.png"
)sunrise
: A regular texture for the sunrise texture. (default:"sunrisebg.png"
)sunrise_visible
: Boolean for whether the sunrise texture is visible. (default:true
)scale
: Float controlling the overall size of the sun. (default:1
) Note: For legacy reasons, the sun is bigger than the moon by a factor of about1.57
for equalscale
values.
get_sun()
: returns a table with the current sun parameters as inset_sun
.set_moon(moon_parameters)
:- Passing no arguments resets the moon to its default values.
moon_parameters
is a table with the following optional fields:visible
: Boolean for whether the moon is visible. (default:true
)texture
: A regular texture for the moon. Setting to""
will re-enable the mesh moon. (default:"moon.png"
, if it exists) The texture appears non-rotated at sunrise / moonset and rotated 180 degrees (upside down) at sunset / moonrise. Note: Relative to the sun, the moon texture is hence rotated by 180°. You can use the^[transformR180
texture modifier to achieve the same orientation.tonemap
: A 512x1 texture containing the tonemap for the moon (default:"moon_tonemap.png"
)scale
: Float controlling the overall size of the moon (default:1
) Note: For legacy reasons, the sun is bigger than the moon by a factor of about1.57
for equalscale
values.
get_moon()
: returns a table with the current moon parameters as inset_moon
.set_stars(star_parameters)
:- Passing no arguments resets stars to their default values.
star_parameters
is a table with the following optional fields:visible
: Boolean for whether the stars are visible. (default:true
)day_opacity
: Float for maximum opacity of stars at day. No effect ifvisible
is false. (default: 0.0; maximum: 1.0; minimum: 0.0)count
: Integer number to set the number of stars in the skybox. Only applies to"skybox"
and"regular"
sky types. (default:1000
)star_color
: ColorSpec, sets the colors of the stars, alpha channel is used to set overall star brightness. (default:#ebebff69
)scale
: Float controlling the overall size of the stars (default:1
)
get_stars()
: returns a table with the current stars parameters as inset_stars
.set_clouds(cloud_parameters)
: set cloud parameters- Passing no arguments resets clouds to their default values.
cloud_parameters
is a table with the following optional fields:density
: from0
(no clouds) to1
(full clouds) (default0.4
)color
: basic cloud color with alpha channel, ColorSpec (default#fff0f0e5
).ambient
: cloud color lower bound, use for a "glow at night" effect. ColorSpec (alpha ignored, default#000000
)height
: cloud height, i.e. y of cloud base (default per conf, usually120
)thickness
: cloud thickness in nodes (default16
)speed
: 2D cloud speed + direction in nodes per second (default{x=0, z=-2}
).
get_clouds()
: returns a table with the current cloud parameters as inset_clouds
.override_day_night_ratio(ratio or nil)
0
...1
: Overrides day-night ratio, controlling sunlight to a specific amount.nil
: Disables override, defaulting to sunlight based on day-night cycle
get_day_night_ratio()
: returns the ratio or nil if it isn't overriddenset_local_animation(idle, walk, dig, walk_while_dig, frame_speed)
: set animation for player model in third person view.- Every animation equals to a
{x=starting frame, y=ending frame}
table. frame_speed
sets the animations frame speed. Default is 30.
- Every animation equals to a
get_local_animation()
: returns idle, walk, dig, walk_while_dig tables andframe_speed
.set_eye_offset([firstperson, thirdperson])
: defines offset vectors for camera per player. An argument defaults to{x=0, y=0, z=0}
if unspecified.- in first person view
- in third person view (max. values
{x=-10/10,y=-10,15,z=-5/5}
)
get_eye_offset()
: returns first and third person offsets.send_mapblock(blockpos)
:- Sends an already loaded mapblock to the player.
- Returns
false
if nothing was sent (note that this can also mean that the client already has the block) - Resource intensive - use sparsely
-
set_lighting(light_definition)
: sets lighting for the playerlight_definition
is a table with the following optional fields:saturation
sets the saturation (vividness). values > 1 increase the saturation values in [0,1) decrease the saturation * This value has no effect on clients who have the "Tone Mapping" shader disabled.shadows
is a table that controls ambient shadowsintensity
sets the intensity of the shadows from 0 (no shadows, default) to 1 (blackness)- This value has no effect on clients who have the "Dynamic Shadows" shader disabled.
exposure
is a table that controls automatic exposure. The basic exposure factor equation ise = 2^exposure_correction / clamp(luminance, 2^luminance_min, 2^luminance_max)
luminance_min
set the lower luminance boundary to use in the calculationluminance_max
set the upper luminance boundary to use in the calculationexposure_correction
correct observed exposure by the given EV valuespeed_dark_bright
set the speed of adapting to bright lightspeed_bright_dark
set the speed of adapting to dark scenecenter_weight_power
set the power factor for center-weighted luminance measurement
-
get_lighting()
: returns the current state of lighting for the player.- Result is a table with the same fields as
light_definition
inset_lighting
.
- Result is a table with the same fields as
respawn()
: Respawns the player using the same mechanism as the death screen, including calling on_respawnplayer callbacks.
PcgRandom
¶
A 32-bit pseudorandom number generator. Uses PCG32, an algorithm of the permuted congruential generator family, offering very strong randomness.
It can be created via PcgRandom(seed)
or PcgRandom(seed, sequence)
.
Methods¶
next()
: return next integer random number [-2147483648
...2147483647
]next(min, max)
: return next integer random number [min
...max
]rand_normal_dist(min, max, num_trials=6)
: return normally distributed random number [min
...max
].- This is only a rough approximation of a normal distribution with:
mean = (max - min) / 2
, andvariance = (((max - min + 1) ^ 2) - 1) / (12 * num_trials)
- Increasing
num_trials
improves accuracy of the approximation
PerlinNoise
¶
A perlin noise generator.
It can be created via PerlinNoise()
or minetest.get_perlin()
.
For minetest.get_perlin()
, the actual seed used is the noiseparams seed
plus the world seed, to create world-specific noise.
PerlinNoise(noiseparams)
PerlinNoise(seed, octaves, persistence, spread)
(Deprecated).
minetest.get_perlin(noiseparams)
minetest.get_perlin(seeddiff, octaves, persistence, spread)
(Deprecated).
Methods¶
get_2d(pos)
: returns 2D noise value atpos={x=,y=}
get_3d(pos)
: returns 3D noise value atpos={x=,y=,z=}
PerlinNoiseMap
¶
A fast, bulk perlin noise generator.
It can be created via PerlinNoiseMap(noiseparams, size)
or
minetest.get_perlin_map(noiseparams, size)
.
For minetest.get_perlin_map()
, the actual seed used is the noiseparams seed
plus the world seed, to create world-specific noise.
Format of size
is {x=dimx, y=dimy, z=dimz}
. The z
component is omitted
for 2D noise, and it must be must be larger than 1 for 3D noise (otherwise
nil
is returned).
For each of the functions with an optional buffer
parameter: If buffer
is
not nil, this table will be used to store the result instead of creating a new
table.
Methods¶
get_2d_map(pos)
: returns a<size.x>
times<size.y>
2D array of 2D noise with values starting atpos={x=,y=}
get_3d_map(pos)
: returns a<size.x>
times<size.y>
times<size.z>
3D array of 3D noise with values starting atpos={x=,y=,z=}
.get_2d_map_flat(pos, buffer)
: returns a flat<size.x * size.y>
element array of 2D noise with values starting atpos={x=,y=}
get_3d_map_flat(pos, buffer)
: Same asget2dMap_flat
, but 3D noisecalc_2d_map(pos)
: Calculates the 2d noise map starting atpos
. The result is stored internally.calc_3d_map(pos)
: Calculates the 3d noise map starting atpos
. The result is stored internally.get_map_slice(slice_offset, slice_size, buffer)
: In the form of an array, returns a slice of the most recently computed noise results. The result slice begins at coordinatesslice_offset
and takes a chunk ofslice_size
. E.g. to grab a 2-slice high horizontal 2d plane of noise starting at buffer offset y = 20:noisevals = noise:get_map_slice({y=20}, {y=2})
It is important to note thatslice_offset
offset coordinates begin at 1, and are relative to the starting position of the most recently calculated noise. To grab a single vertical column of noise starting at map coordinates x = 1023, y=1000, z = 1000:noise:calc_3d_map({x=1000, y=1000, z=1000})
noisevals = noise:get_map_slice({x=24, z=1}, {x=1, z=1})
PlayerMetaRef
¶
Player metadata.
Uses the same method of storage as the deprecated player attribute API, so
data there will also be in player meta.
Can be obtained using player:get_meta()
.
Methods¶
- All methods in MetaDataRef
PseudoRandom
¶
A 16-bit pseudorandom number generator. Uses a well-known LCG algorithm introduced by K&R.
It 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) == 32767) or ((max-min) <= 6553))
must be true due to the simple implementation making bad distribution otherwise.
Raycast
¶
A raycast on the map. It works with selection boxes. Can be used as an iterator in a for loop as:
local ray = Raycast(...)
for pointed_thing in ray do
...
end
The map is loaded as the ray advances. If the map is modified after the
Raycast
is created, the changes may or may not have an effect on the object.
It can be created via Raycast(pos1, pos2, objects, liquids)
or
minetest.raycast(pos1, pos2, objects, liquids)
where:
pos1
: start of the raypos2
: end of the rayobjects
: if false, only nodes will be returned. Default is true.liquids
: if false, liquid nodes (liquidtype ~= "none"
) won't be returned. Default is false.
Limitations¶
Raycasts don't always work properly for attached objects as the server has no knowledge of models & bones.
Rotated selectionboxes paired with automatic_rotate
are not reliable either since the server
can't reliably know the total rotation of the objects on different clients (which may differ on a per-client basis).
The server calculates the total rotation incurred through automatic_rotate
as a "best guess"
assuming the object was active & rotating on the client all the time since its creation.
This may be significantly out of sync with what clients see.
Additionally, network latency and delayed property sending may create a mismatch of client- & server rotations.
In singleplayer mode, raycasts on objects with rotated selectionboxes & automatic rotate will usually only be slightly off; toggling automatic rotation may however cause errors to add up.
In multiplayer mode, the error may be arbitrarily large.
Methods¶
next()
: returns apointed_thing
with exact pointing location- Returns the next thing pointed by the ray or nil.
SecureRandom
¶
Interface for the operating system's crypto-secure PRNG.
It can be created via SecureRandom()
. The constructor returns nil if a
secure random device cannot be found on the system.
Methods¶
next_bytes([count])
: return nextcount
(default 1, capped at 2048) many random bytes, as a string.
Settings
¶
An interface to read config files in the format of minetest.conf
.
It can be created via Settings(filename)
.
Methods¶
get(key)
: returns a valueget_bool(key, [default])
: returns a booleandefault
is the value returned ifkey
is not found.- Returns
nil
ifkey
is not found anddefault
not specified.
get_np_group(key)
: returns a NoiseParams tableget_flags(key)
:- Returns
{flag = true/false, ...}
according to the set flags. - Is currently limited to mapgen flags
mg_flags
and mapgen-specific flags likemgv5_spflags
.
- Returns
set(key, value)
- Setting names can't contain whitespace or any of
="{}#
. - Setting values can't contain the sequence
\n"""
. - Setting names starting with "secure." can't be set on the main settings
object (
minetest.settings
).
- Setting names can't contain whitespace or any of
set_bool(key, value)
- See documentation for set() above.
set_np_group(key, value)
value
is a NoiseParams table.- Also, see documentation for set() above.
remove(key)
: returns a boolean (true
for success)get_names()
: returns{key1,...}
write()
: returns a boolean (true
for success)- Writes changes to file.
to_table()
: returns{[key1]=value1,...}
Format¶
The settings have the format key = value
. Example:
foo = example text
bar = """
Multiline
value
"""
StorageRef
¶
Mod metadata: per mod metadata, saved automatically.
Can be obtained via minetest.get_mod_storage()
during load time.
WARNING: This storage backend is incapable of saving raw binary data due to restrictions of JSON.
Methods¶
- All methods in MetaDataRef