From Minetest Developer Wiki
Jump to: navigation, search
Mbox warning.png This page contains unofficial Lua API documentation and is likely to be outdated or wrong.
For the official and up-to-date documentation, refer to lua_api.txt found in your Minetest installation directory under doc.
Mbox warning.png This page has been proposed for deletion for the following reason: "Contains unofficial and potentially outdated, redundant and inconsistent Lua API information"
If you don't think that this page should be deleted, please explain why on the talk page.

These are players in the game. It inherits all the properties of ObjectRef.


  • get_player_name() — returns "" if is not a player
  • get_player_velocity() — returns player speed with a table {x,y,z}, or nil if not a player
  • add_player_velocity(vel)
  • Adds to player velocity, this happens client-side and only once.
  • 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_player_velocity({x=0, y=6.5, z=0})` is equivalent to pressing the jump key (assuming default settings)
  • get_look_dir() — returns the camera direction as a unit vector
  • get_look_vertical() — returns pitch in radians
  • Angle ranges between -pi/2 and pi/2, which are straight up and down respectively.
  • get_look_horizontal() — returns yaw in radians
  • Angle is counter-clockwise from the +z direction.
  • set_look_vertical(pitch) — set pitch in radians.
  • pitch: Angle from looking forward, where positive is downwards.
  • set_look_horizontal(yaw) — set yaw in radians.
Parameter has the same meaning as the return value of get_look_horizontal, but it has an offset against get_look_yaw of math.pi/2
Example values :
dir Δx dir Δz Value
0 1 0
0 -1 π
1 0 3π/2
-1 0 π/2
To convert a Δx,Δz to a yaw value use following formula :
if Δx < 0 then
yaw = atan2(-Δx, Δz) + 2π
yaw = atan2(-Δx, Δz)
player object look horizontal vertical yaw.png
  • Angle is counter-clockwise from the +x direction.
  • set_look_pitch(pitch) - DEPRECATED use set_look_vertical
  • set_look_yaw(yaw) - DEPRECATED use set_look_horizontal
  • get_breath() returns players breath
  • set_breath(value)
    • example for max breath = 11:
    • 0 player is drowning
    • 1-10 number of bubbles remain
    • 11 bubbles bar is not shown
  • set_attribute(attribute, value) — DEPRECATED, use get_meta() instead
    • set an extra player attribute to value.
    • The value must be a string, or a number which will be converted to a string.
    • Pass nil as value to remove the attribute
  • get_attribute(attribute) — DEPRECATED, use get_meta() instead
    • returns the value for the extra player attribute or nil if this attribute had not been set.
    • The return value is always a string
  • get_meta — Returns a PlayerMetaRef.
  • set_inventory_formspec("string")
  • get_inventory_formspec() — returns formspec string
  • set_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 behaviour.
    • Only affects formspecs shown after this is called.
  • get_formspec_prepend() — returns a formspec string.
  • get_player_control() — Returns table with player's pressed keys.
    • Format: {jump=bool, right=bool, left=bool, LMB=bool, RMB=bool, sneak=bool, aux1=bool, down=bool, up=bool}
  • get_player_control_bits() — Returns an integer bitfield with player's pressed keys.
    • Bits: 0/up, 1/down, 2/left, 3/right, 4/jump, 5/aux1, 6/sneak, 7/LMB, 8/RMB
  • set_physics_override(table)
    • Table must be like: {
      • speed = 1.0, -- multiplier to default value
      • jump = 1.0, -- multiplier to default value
      • gravity = 1.0, -- multiplier to default value
      • sneak = true, -- whether player can sneak
      • sneak_glitch = true, -- whether player can use the sneak glitch
      • new_move = false, -- use new move/sneak code
    • }
  • get_physics_override() -- returns a table by set_physics_override
  • hud_add(hud definition) Shows a HUD element to the player, returns ID number on success
  • hud_remove(id) Removes a HUD element shown to the player
  • hud_change(id, stat, value) Changes a HUD element shown to the player
    • element stat values: position, name, scale, text, number, item, dir
  • hud_get(id) Gets a HUD element definition
  • hud_set_flags(flags) Sets specified HUD flags to true/false
    • flags: (is visible) hotbar, healthbar, crosshair, wielditem, breathbar, minimap, minimap_radar
    • pass a table containing a true/false value of each flag to be set or unset
    • if a flag is nil, the flag is not modified
    • 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 when minimap is true
  • hud_get_flags() Returns a table containing the status of HUD flags
  • hud_set_hotbar_itemcount(count) Set number of items in builtin hotbar
    • count must be between 1 and 32
  • hud_get_hotbar_itemcount() Returns the number of items in builtin hotbar
  • hud_set_hotbar_image(texturename) Sets background image for hotbar
  • hud_get_hotbar_image() Returns the background image name for hotbar
  • hud_set_hotbar_selected_image(texturename) Sets image for hotbar selected item
  • hud_get_hotbar_selected_image() Returns the image name for hotbar selected item
  • set_sky(bgcolor, type, {texture names}, clouds)
    • bgcolor: {r=0...255, g=0...255, b=0...255} or nil, defaults to white
    • 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)
Note: currently does not work directly in on_joinplayer; use minetest.after(0) in there.

  • get_sky() — returns bgcolor, type, table of textures, clouds
  • set_clouds(parameters) — set cloud parameters
    • parameters is a table with the following optional fields:
      • density: from 0 (no clouds) to 1 (full clouds) (default 0.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, usually 120)
      • thickness: cloud thickness in nodes (default 16)
      • speed: 2D cloud speed + direction in nodes per second (default {x=0, z=-2}).
  • get_clouds(parameters) — returns a table with the current cloud parameters as in set_clouds.
  • override_day_night_ratio(ratio) — Overrides day/night ratio, controlling sunlight to a specific amount.
    • ratio — Ratio from 0 to 1, or nil to reset to default behavior.
  • get_day_night_ratio() — returns the ratio or nil if it isn't overridden
  • set_local_animation(stand/idle, walk, dig, walk+dig, frame_speed=frame_speed) — Sets animation for player model in third person view.
    • every parameter beside frame_speed is a table of the form {x = start_frame, y = end_frame}
  • get_local_animation(player) — Returns 4 frames and frame speed. See set_local_animation
  • set_eye_offset(pos1p, pos3p) — Defines camera offset value for player. Offsets are relative to the default camera position for the given view, not relative to the player's position as returned by getpos() and not relative to previous calls (so using {x=0,y=0,z=0} resets to the default position for the view). Offset vectors are in a left-handed coordinate system where x is toward the player's right, y is up, and z is toward the player's front.
    • pos1p — Offset vector in first person view.
    • pos3p — Offset vector in third person view. Ranges: x=-10..10, y=-10..15, z=-5..5
  • get_eye_offset() — Returns eye offset. See set_eye_offset()
  • send_mapblock(blockpos)
    • Sends a server-side loaded mapblock to the player.
    • Returns false if failed.
    • Resource intensive - use sparsely
    • To get blockpos, integer divide pos by 16

Inherited from ObjectRef

  • get_pos() — returns {x=num, y=num, z=num}.
  • set_pos(pos)
  • move_to(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
  • clicker — another ObjectRef
  • get_hp() — returns number of hitpoints (maximal 20 by default).
  • set_hp(hp) — set number of hitpoints (2 * number of hearts)
  • get_inventory() — returns the InvRef of the object.
  • 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() — returns the wielded item (ItemStack). This is essentially just a pseudonym for object:get_inventory():get_stack(object:get_wield_list(), object:get_wield_index()) so please note the caveats for inventory manipulation (changes will need to be "committed" by calling object:set_wielded_item(modifiedStack) after modifying the stack unless they are done in the context of a callback that implicitly modifies the stack; see minetest.register_node#on_use).
  • set_wielded_item(item) — replaces the wielded item, returns true if successful
  • set_armor_groups({group1=rating, group2=rating, ...})
  • get_armor_groups() - Returns {group1=rating, group2=rating, ...})
  • set_animation({x=1,y=1}, frame_speed=15, frame_blend=0)
  • get_animation() - Returns frames, frame_speed, frame_blend, frame_loop.
  • frames - {x=int,y=int}
  • frame_speed - integer
  • frame_blend - integer
  • frame_loop - true if the animation is looping
  • set_animation_frame_speed(frame_speed)
  • frame_speed - number, default: 15.0
  • set_attach(parent, "", {x=0,y=0,z=0}, {x=0,y=0,z=0})
  • get_attach() — returns nil when not attached or multiple values:
  • parentObjectRef
  • bonestring of the bone name
  • position: attachment position offset
  • rotation: fixed child attachment rotation
  • set_detach()
  • set_bone_position(bone = "", position = {x=0,y=0,z=0}, rotation = {x=0,y=0,z=0})
  • get_bone_position(bone) - returns position and rotation of bone
  • set_properties({object property table})
  • get_properties() - returns object property table
  • is_player() - returns true for players, false otherwise
  • get_nametag_attributes() - returns table with attributes
  • set_nametag_attributes(attributes)
  • sets attributes of nametag of the object
  • attributes: {color = ColorSpec, text = string}
Personal tools