Class reference¶

Sorted alphabetically.

AreaStore¶

A fast access data structure to store areas, and find areas near a given position or area. Every area has a data string attribute to store additional information. You can create an empty AreaStore by calling AreaStore(), or AreaStore(type_name). The mod decides where to save and load AreaStore. If you chose the parameter-less constructor, a fast implementation will be automatically chosen for you.

Methods¶

• get_area(id, include_borders, include_data)

  • Returns the area information about the specified ID.
  • Returned values are either of these:

      nil  -- Area not found
      true -- Without `include_borders` and `include_data`
      {
          min = pos, max = pos -- `include_borders == true`
          data = string        -- `include_data == true`
      }
    

• get_areas_for_pos(pos, include_borders, include_data)

  • Returns all areas as table, indexed by the area ID.
  • Table values: see get_area.
• get_areas_in_area(edge1, edge2, accept_overlap, include_borders, include_data)
  • Returns all areas that contain all nodes inside the area specified by edge1 and edge2 (inclusive).
  • accept_overlap: if true, areas are returned that have nodes in common (intersect) with the specified area.
  • Returns the same values as get_areas_for_pos.
• insert_area(edge1, edge2, data, [id]): inserts an area into the store.
  • Returns the new area's ID, or nil if the insertion failed.
  • The (inclusive) positions edge1 and edge2 describe the area.
  • data is a string stored with the area.
  • id (optional): will be used as the internal area ID if it is an unique number between 0 and 2^32-2.
• reserve(count): reserves resources for at most count many contained areas. Only needed for efficiency, and only some implementations profit.
• 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. Like to_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. Like from_string(), but reads the data from a file.

InvRef¶

An InvRef is a 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
  • returns false on error (e.g. invalid listname or size)
• 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)
• get_lists(): returns list of inventory lists
• set_lists(lists): sets inventory lists (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, [match_meta]): returns true if the stack of items can be fully taken from the list. If match_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 an ItemStack) -- 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 use set_stack with an empty ItemStack.
• get_location(): returns a location compatible to core.get_inventory(location).
  • returns {type="undefined"} in case location is not known

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 inventory
• allow_take/allow_metadata_inventory_take: Taking items from the inventory
• allow_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 inventory
• on_take/on_metadata_inventory_take: Taking items from the inventory
• on_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(): returns true 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 cleared
  • count: 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 cleared
  • wear: number, unsigned 16 bit integer
• get_meta(): returns ItemStackMetaRef. See section for more details
• get_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(): 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
  • amount: number, integer
• add_item(item): returns leftover ItemStack
  • Put some item or stack onto this stack
• item_fits(item): returns true if item or stack can be fully added to this one.
• take_item(n): returns taken ItemStack
  • Take (and remove) up to n items from this stack
  • n: number, default: 1
• peek_item(n): returns taken ItemStack
  • Copy (don't remove) up to n items from this stack
  • n: number, default: 1

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.

Methods¶

• contains(key): Returns true if key present, otherwise false.
  • Returns nil when the MetaData is inexistent.
• get(key): Returns nil 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): Returns 0 if key not present.
• set_float(key, value)
• get_float(key): Returns 0 if key not present.
• to_table(): returns nil or a table with keys:
  • fields: key-value storage
  • inventory: {list1 = {}, ...}} (NodeMetaRef only)
• from_table(nil or {})
  • Any non-table value will clear the metadata
  • See [Node Metadata] for an example
  • returns true on success
• equals(other)
  • returns true if this metadata has the same key-value pairs as other

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.
• is_writeable(): returns true if channel is writeable and mod can send over it.
• send_all(message): Send message 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 core.get_meta(pos).

Methods¶

• All methods in MetaDataRef
• get_inventory(): returns InvRef
• 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 core.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 equals 0, timer is inactive
• get_elapsed(): returns current elapsed time in seconds
  • the node's on_timer function will be called after (timeout - elapsed) seconds.
• is_started(): returns boolean state of timer
  • returns true if timer is started, otherwise false

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.

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 = another ObjectRef,
  • time_from_last_punch = time since last punch action of the puncher
  • direction: can be nil
• right_click(clicker); clicker is another ObjectRef
• get_hp(): returns number of health points
• set_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 the player's object properties
• get_inventory(): returns an InvRef for players, otherwise returns nil
• 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 an ItemStack
• set_wielded_item(item): replaces the wielded item, returns true if successful.
• set_armor_groups({group1=rating, group2=rating, ...})
• get_armor_groups(): returns a table with the armor group ratings
• set_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(): returns range, frame_speed, frame_blend and frame_loop.
• set_animation_frame_speed(frame_speed)
  • frame_speed: number, default: 15.0
• set_attach(parent[, bone, position, rotation, forced_visible])
  • bone: string. Default is "", the root bone
  • position: {x=num, y=num, z=num}, relative, default {x=0, y=0, z=0}
  • rotation: {x=num, y=num, z=num} = Rotation on each axis, in degrees. Default {x=0, y=0, z=0}
  • forced_visible: Boolean to control whether the attached entity should appear in first person. Default false.
• 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 bone
  • position: {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 bone
• set_properties(object property table)
• get_properties(): returns object property table
• is_player(): returns true for players, false otherwise
• get_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 returning nil.
• 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 vector
• set_rotation(rot)
  • rot is a vector (radians). X is pitch (elevation), Y is yaw (heading) and Z is roll (bank).
• get_rotation(): returns the rotation, a vector (radians)
• set_yaw(yaw): sets the yaw in radians (heading).
• get_yaw(): returns number in radians
• set_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 modifier
• set_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 frame x 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)
• get_luaentity()

Player only (no-op for other objects)¶

• get_player_name(): returns "" if is not a player
• get_player_velocity(): DEPRECATED, use get_velocity() instead. table {x, y, z} representing the player's instantaneous velocity in nodes/s
• add_player_velocity(vel): DEPRECATED, use add_velocity(vel) instead.
• get_look_dir(): get camera direction as a unit vector
• get_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. Use get_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. Use get_look_horizontal.
  • Angle is counter-clockwise from the +x direction.
• set_look_pitch(radians): sets look pitch - Deprecated. Use set_look_vertical.
• set_look_yaw(radians): sets look yaw - Deprecated. Use set_look_horizontal.
• get_breath(): returns player's breath
• set_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)
• set_fov(fov, is_multiplier, transition_time): Sets player's FOV
  • fov: FOV value.
  • is_multiplier: Set to true if the FOV value is a multiplier. Defaults to false.
  • 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 is nil, 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
• get_inventory_formspec(): returns a 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(formspec): returns a formspec string.
• copy_to_clipboard(text): Copies text to the player's clipboard.
• 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, zoom, and tabb.
  • The fields LMB and RMB are equal to dig and place respectively, and exist only to preserve backwards compatibility.
• 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
  • 10 - tabb
• 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. When false the exact old code is used for the specific old sneak behaviour (default: true)
• get_physics_override(): returns the table given to set_physics_override
• hud_add(hud definition): add a HUD element described by HUD def, returns ID number on success
• hud_remove(id): remove the HUD element of the specified id
• hud_change(id, stat, value): change a value of a previously added HUD element.
  • element stat values: position, name, scale, text, number, item, dir
• hud_get(id): gets the HUD element definition structure of the specified ID
• hud_set_flags(flags): sets specified HUD flags of player.
  • flags: A table with the following fields set to boolean values
    • hotbar
    • 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 when minimap is true
    • basic_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 the debug privilege.
  • 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.
• hud_set_hotbar_itemcount(count): sets number of items in builtin hotbar
  • count: number of items, must be between 1 and 32
• hud_get_hotbar_itemcount: returns number of visible items
• hud_set_hotbar_image(texturename)
  • sets background image for hotbar
• hud_get_hotbar_image: returns texturename
• hud_set_hotbar_selected_image(texturename)
  • sets image for selected item of hotbar
• hud_get_hotbar_selected_image: returns texturename
• set_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 off
      • surface: Minimap in surface mode
      • radar: Minimap in radar mode
      • texture: 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 minimap
    • texture: Only for texture type, name of the texture to display
    • scale: Only for texture type, scale of the texture map in nodes per pixel (for example a scale 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 or set_stars indicates whether set_sky accepts this format. Check the legacy format otherwise.
  • sky_parameters is a table with the following optional fields:
    • base_color: ColorSpec, changes fog in "skybox" and "plain".
    • 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.
    • 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 containing the following values, alpha is ignored:
      • day_sky: ColorSpec, for the top half of the "regular" sky during the day. (default: #8cbafa)
      • day_horizon: ColorSpec, for the bottom half of the "regular" sky during the day. (default: #9bc1f0)
      • dawn_sky: ColorSpec, for the top half of the "regular" 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 "regular" 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 "regular" sky during the night. (default: #006aff) 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 "regular" 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. Only applies to the "regular" sky. (default: #646464)
      • fog_sun_tint: ColorSpec, changes the fog tinting for the sun at sunrise and sunset.
      • fog_moon_tint: ColorSpec, changes the fog tinting for the moon at sunrise and sunset.
      • fog_tint_type: string, changes which mode the directional fog abides by, "custom" uses sun_tint and moon_tint, while "default" uses the classic MultiCraft sun and moon tinting. Will use tonemaps, if set to "default". (default: "default")
• set_sky(base_color, type, {texture names}, clouds)
  • Deprecated. Use set_sky(sky_parameters)
  • base_color: ColorSpec, defaults to white
  • type: 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)
• get_sky(): returns base_color, type, table of textures, clouds.
• get_sky_color(): returns a table with the sky_color parameters as in set_sky.
• set_sun(sun_parameters):
  • 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")
    • 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)
• get_sun(): returns a table with the current sun parameters as in set_sun.
• set_moon(moon_parameters):
  • 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")
    • 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)
• get_moon(): returns a table with the current moon parameters as in set_moon.
• set_stars(star_parameters):
  • star_parameters is a table with the following optional fields:
    • visible: Boolean for whether the stars are visible. (default: true)
    • 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 in set_stars.
• set_clouds(cloud_parameters): set cloud parameters
  • cloud_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(): returns a table with the current cloud parameters as in set_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 overridden
• set_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.
• get_local_animation(): returns idle, walk, dig, walk_while_dig tables and frame_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 a server-side loaded mapblock to the player.
  • Returns false if failed.
  • Resource intensive - use sparsely
  • To get blockpos, integer divide pos by 16

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, and
  • variance = (((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 core.get_perlin(). For core.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).

core.get_perlin(noiseparams) core.get_perlin(seeddiff, octaves, persistence, spread) (Deprecated).

Methods¶

• get_2d(pos): returns 2D noise value at pos={x=,y=}
• get_3d(pos): returns 3D noise value at pos={x=,y=,z=}

PerlinNoiseMap¶

A fast, bulk perlin noise generator.

It can be created via PerlinNoiseMap(noiseparams, size) or core.get_perlin_map(noiseparams, size). For core.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 at pos={x=,y=}
• get_3d_map(pos): returns a <size.x> times <size.y> times <size.z> 3D array of 3D noise with values starting at pos={x=,y=,z=}.
• get_2d_map_flat(pos, buffer): returns a flat <size.x * size.y> element array of 2D noise with values starting at pos={x=,y=}
• get_3d_map_flat(pos, buffer): Same as get2dMap_flat, but 3D noise
• calc_2d_map(pos): Calculates the 2d noise map starting at pos. The result is stored internally.
• calc_3d_map(pos): Calculates the 3d noise map starting at pos. 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 coordinates slice_offset and takes a chunk of slice_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 that slice_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 core.raycast(pos1, pos2, objects, liquids) where:

• pos1: start of the ray
• pos2: end of the ray
• objects: if false, only nodes will be returned. Default is true.
• liquids: if false, liquid nodes won't be returned. Default is false.

Methods¶

• next(): returns a pointed_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 next count (default 1, capped at 2048) many random bytes, as a string.

Settings¶

An interface to read config files in the format of multicraft.conf.

It can be created via Settings(filename).

Methods¶

• get(key): returns a value
• get_bool(key, [default]): returns a boolean
  • default is the value returned if key is not found.
  • Returns nil if key is not found and default not specified.
• get_np_group(key): returns a NoiseParams table
• get_flags(key):
  • Returns {flag = true/false, ...} according to the set flags.
  • Is currently limited to mapgen flags mg_flags and mapgen-specific flags like mgv5_spflags.
• 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 (core.settings).
• 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 core.get_mod_storage() during load time.

WARNING: This storage backend is incaptable to save raw binary data due to restrictions of JSON.

Methods¶

• All methods in MetaDataRef