ModChannel

An interface to use mod channels on client and server

Methods

  • leave(): leave the mod channel.
    • Client leaves channel channel_name.
    • No more incoming or outgoing messages can be sent to this channel from client mods.
    • This invalidate all future object usage
    • Ensure your set mod_channel to nil after that to free Lua resources
  • is_writeable(): returns true if channel is writable and mod can send over it.
  • send_all(message): Send message though the mod channel.
    • If mod channel is not writable or invalid, message will be dropped.
    • Message size is limited to 65535 characters by protocol.

Minimap

An interface to manipulate minimap on client UI

Methods

  • show(): shows the minimap (if not disabled by server)
  • hide(): hides the minimap
  • set_pos(pos): sets the minimap position on screen
  • get_pos(): returns the minimap current position
  • set_angle(deg): sets the minimap angle in degrees
  • get_angle(): returns the current minimap angle in degrees
  • set_mode(mode): sets the minimap mode (0 to 6)
  • get_mode(): returns the current minimap mode
  • set_shape(shape): Sets the minimap shape. (0 = square, 1 = round)
  • get_shape(): Gets the minimap shape. (0 = square, 1 = round)

Camera

An interface to get or set information about the camera and camera-node. Please do not try to access the reference until the camera is initialized, otherwise the reference will be nil.

Methods

  • set_camera_mode(mode)
    • Pass 0 for first-person, 1 for third person, and 2 for third person front
  • get_camera_mode()
    • Returns 0, 1, or 2 as described above
  • get_fov()
    • Returns a table with X, Y, maximum and actual FOV in degrees:
     {
         x = number,
         y = number,
         max = number,
         actual = number
     }
  • get_pos()
    • Returns position of camera with view bobbing
  • get_offset()
    • Returns eye offset vector
  • get_look_dir()
    • Returns eye direction unit vector
  • get_look_vertical()
    • Returns pitch in radians
  • get_look_horizontal()
    • Returns yaw in radians
  • get_aspect_ratio()
    • Returns aspect ratio of screen

LocalPlayer

An interface to retrieve information about the player. This object will only be available after the client is initialized. Earlier accesses will yield a nil value.

Methods:

  • get_pos()
    • returns current player current position
  • get_velocity()
    • returns player speed vector
  • get_hp()
    • returns player HP
  • get_name()
    • returns player name
  • get_wield_index()
    • returns the index of the wielded item
  • get_wielded_item()
    • returns the itemstack the player is holding
  • is_attached()
    • returns true if player is attached
  • is_touching_ground()
    • returns true if player touching ground
  • is_in_liquid()
    • returns true if player is in a liquid (This oscillates so that the player jumps a bit above the surface)
  • is_in_liquid_stable()
    • returns true if player is in a stable liquid (This is more stable and defines the maximum speed of the player)
  • get_liquid_viscosity()
    • returns liquid viscosity (Gets the viscosity of liquid to calculate friction)
  • is_climbing()
    • returns true if player is climbing
  • swimming_vertical()
    • returns true if player is swimming in vertical
  • get_physics_override()
    • returns:
    {
        speed = float,
        jump = float,
        gravity = float,
        sneak = boolean,
        sneak_glitch = boolean,
        new_move = boolean,
    }
  • get_override_pos()
    • returns override position
  • get_last_pos()
    • returns last player position before the current client step
  • get_last_velocity()
    • returns last player speed
  • get_breath()
    • returns the player's breath
  • get_movement_acceleration()
    • returns acceleration of the player in different environments:
    {
       fast = float,
       air = float,
       default = float,
    }
  • get_movement_speed()
    • returns player's speed in different environments:
    {
       walk = float,
       jump = float,
       crouch = float,
       fast = float,
       climb = float,
    }
  • get_movement()
    • returns player's movement in different environments:
    {
       liquid_fluidity = float,
       liquid_sink = float,
       liquid_fluidity_smooth = float,
       gravity = float,
    }
  • get_last_look_horizontal():
    • returns last look horizontal angle
  • get_last_look_vertical():
    • returns last look vertical angle
  • get_control():
    • returns pressed player controls
    {
       up = boolean,
       down = boolean,
       left = boolean,
       right = boolean,
       jump = boolean,
       aux1 = boolean,
       sneak = boolean,
       zoom = boolean,
       dig = boolean,
       place = boolean,
    }
  • get_armor_groups()
    • returns a table with the armor group ratings
  • hud_add(definition)
    • add a HUD element described by HUD def, returns ID number on success and nil on failure.
    • See HUD definition
  • hud_get(id)
    • returns the definition of the HUD with that ID number or nil, if non-existent.
  • hud_remove(id)
    • remove the HUD element of the specified id, returns true on success
  • hud_change(id, stat, value)
    • change a value of a previously added HUD element
    • element stat values: position, name, scale, text, number, item, dir
    • Returns true on success, otherwise returns nil

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): returns a boolean
  • set(key, value)
  • remove(key): returns a boolean (true for success)
  • get_names(): returns {key1,...}
  • write(): returns a boolean (true for success)
    • write changes to file
  • to_table(): returns {[key1]=value1,...}

NodeMetaRef

Node metadata: reference extra data and functionality stored in a node. Can be obtained via core.get_meta(pos).

Methods

  • get_string(name)
  • get_int(name)
  • get_float(name)
  • to_table(): returns nil or a table with keys:
    • fields: key-value storage
    • inventory: {list1 = {}, ...}}

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.

Definitions

  • core.get_node_def(nodename)
  • core.get_item_def(itemstring)
    • Returns item definition table of itemstring

Node Definition

    {
        has_on_construct = bool,        -- Whether the node has the on_construct callback defined
        has_on_destruct = bool,         -- Whether the node has the on_destruct callback defined
        has_after_destruct = bool,      -- Whether the node has the after_destruct callback defined
        name = string,                  -- The name of the node e.g. "air", "default:dirt"
        groups = table,                 -- The groups of the node
        paramtype = string,             -- Paramtype of the node
        paramtype2 = string,            -- ParamType2 of the node
        drawtype = string,              -- Drawtype of the node
        mesh = <string>,                -- Mesh name if existant
        minimap_color = <Color>,        -- Color of node on minimap *May not exist*
        visual_scale = number,          -- Visual scale of node
        alpha = number,                 -- Alpha of the node. Only used for liquids
        color = <Color>,                -- Color of node *May not exist*
        palette_name = <string>,        -- Filename of palette *May not exist*
        palette = <{                    -- List of colors
            Color,
            Color
        }>,
        waving = number,                -- 0 of not waving, 1 if waving
        connect_sides = number,         -- Used for connected nodes
        connects_to = {                 -- List of nodes to connect to
            "node1",
            "node2"
        },
        post_effect_color = Color,      -- Color overlayed on the screen when the player is in the node
        leveled = number,               -- Max level for node
        sunlight_propogates = bool,     -- Whether light passes through the block
        light_source = number,          -- Light emitted by the block
        is_ground_content = bool,       -- Whether caves should cut through the node
        walkable = bool,                -- Whether the player collides with the node
        pointable = bool,               -- Whether the player can select the node
        diggable = bool,                -- Whether the player can dig the node
        climbable = bool,               -- Whether the player can climb up the node
        buildable_to = bool,            -- Whether the player can replace the node by placing a node on it
        rightclickable = bool,          -- Whether the player can place nodes pointing at this node
        damage_per_second = number,     -- HP of damage per second when the player is in the node
        liquid_type = <string>,         -- A string containing "none", "flowing", or "source" *May not exist*
        liquid_alternative_flowing = <string>, -- Alternative node for liquid *May not exist*
        liquid_alternative_source = <string>, -- Alternative node for liquid *May not exist*
        liquid_viscosity = <number>,    -- How fast the liquid flows *May not exist*
        liquid_renewable = <boolean>,   -- Whether the liquid makes an infinite source *May not exist*
        liquid_range = <number>,        -- How far the liquid flows *May not exist*
        drowning = bool,                -- Whether the player will drown in the node
        floodable = bool,               -- Whether nodes will be replaced by liquids (flooded)
        node_box = table,               -- Nodebox to draw the node with
        collision_box = table,          -- Nodebox to set the collision area
        selection_box = table,          -- Nodebox to set the area selected by the player
        sounds = {                      -- Table of sounds that the block makes
            sound_footstep = SimpleSoundSpec,
            sound_dig = SimpleSoundSpec,
            sound_dug = SimpleSoundSpec
        },
        legacy_facedir_simple = bool,   -- Whether to use old facedir
        legacy_wallmounted = bool       -- Whether to use old wallmounted
    }

Item Definition

    {
        name = string,                  -- Name of the item e.g. "default:stone"
        description = string,           -- Description of the item e.g. "Stone"
        type = string,                  -- Item type: "none", "node", "craftitem", "tool"
        inventory_image = string,       -- Image in the inventory
        wield_image = string,           -- Image in wieldmesh
        palette_image = string,         -- Image for palette
        color = Color,                  -- Color for item
        wield_scale = Vector,           -- Wieldmesh scale
        stack_max = number,             -- Number of items stackable together
        usable = bool,                  -- Has on_use callback defined
        liquids_pointable = bool,       -- Whether you can point at liquids with the item
        tool_capabilities = <table>,    -- If the item is a tool, tool capabilities of the item
        groups = table,                 -- Groups of the item
        sound_place = SimpleSoundSpec,  -- Sound played when placed
        sound_place_failed = SimpleSoundSpec, -- Sound played when placement failed
        node_placement_prediction = string -- Node placed in client until server catches up
    }

Chat command definition (register_chatcommand)

    {
        params = "<name> <privilege>", -- Short parameter description
        description = "Remove privilege from player", -- Full description
        func = function(param),        -- Called when command is run.
                                       -- Returns boolean success and text output.
    }

Server info

{
    address = "core.example.org", -- The domain name/IP address of a remote server or "" for a local server.
    ip = "203.0.113.156",             -- The IP address of the server.
    port = 30000,                     -- The port the client is connected to.
    protocol_version = 30             -- Will not be accurate at start up as the client might not be connected to the server yet, in that case it will be 0.
}

HUD Definition (hud_add, hud_get)

    {
        hud_elem_type = "image", -- see HUD element types, default "text"
    --  ^ type of HUD element, can be either of "image", "text", "statbar", or "inventory"
        position = {x=0.5, y=0.5},
    --  ^ Left corner position of element, default `{x=0,y=0}`.
        name = "<name>",    -- default ""
        scale = {x=2, y=2}, -- default {x=0,y=0}
        text = "<text>",    -- default ""
        number = 2,         -- default 0
        item = 3,           -- default 0
    --  ^ Selected item in inventory.  0 for no item selected.
        direction = 0,      -- default 0
    --  ^ Direction: 0: left-right, 1: right-left, 2: top-bottom, 3: bottom-top
        alignment = {x=0, y=0},   -- default {x=0, y=0}
    --  ^ See "HUD Element Types"
        offset = {x=0, y=0},      -- default {x=0, y=0}
    --  ^ See "HUD Element Types"
        size = { x=100, y=100 },  -- default {x=0, y=0}
    --  ^ Size of element in pixels
    }