Nodes

Nodes are the bulk data of the world: cubes and other things that take the space of a cube. Huge amounts of them are handled efficiently, but they are quite static.

The definition of a node is stored and can be accessed by using

minetest.registered_nodes[node.name]

See [Registered definitions].

Nodes are passed by value between Lua and the engine. They are represented by a table:

{name="name", param1=num, param2=num}

param1 and param2 are 8-bit integers ranging from 0 to 255. The engine uses them for certain automated functions. If you don't use these functions, you can use them to store arbitrary values.

Node paramtypes

The functions of param1 and param2 are determined by certain fields in the node definition.

param1 is reserved for the engine when paramtype != "none":

  • paramtype = "light"
    • The value stores light with and without sun in its upper and lower 4 bits respectively.
    • Required by a light source node to enable spreading its light.
    • Required by the following drawtypes as they determine their visual brightness from their internal light value:
      • torchlike
      • signlike
      • firelike
      • fencelike
      • raillike
      • nodebox
      • mesh
      • plantlike
      • plantlike_rooted

param2 is reserved for the engine when any of these are used:

  • liquidtype = "flowing"
    • The level and some flags of the liquid is stored in param2
  • drawtype = "flowingliquid"
    • The drawn liquid level is read from param2
  • drawtype = "torchlike"
  • drawtype = "signlike"
  • paramtype2 = "wallmounted"
    • The rotation of the node is stored in param2. You can make this value by using minetest.dir_to_wallmounted().
  • paramtype2 = "facedir"
    • The rotation of the node is stored in param2. Furnaces and chests are rotated this way. Can be made by using minetest.dir_to_facedir().
    • Values range 0 - 23
    • facedir / 4 = axis direction: 0 = y+, 1 = z+, 2 = z-, 3 = x+, 4 = x-, 5 = y-
    • facedir modulo 4 = rotation around that axis
  • paramtype2 = "leveled"
    • Only valid for "nodebox" with 'type = "leveled"', and "plantlike_rooted".
      • Leveled nodebox:
        • The level of the top face of the nodebox is stored in param2.
        • The other faces are defined by 'fixed = {}' like 'type = "fixed"' nodeboxes.
        • The nodebox height is (param2 / 64) nodes.
        • The maximum accepted value of param2 is 127.
      • Rooted plantlike:
        • The height of the 'plantlike' section is stored in param2.
        • The height is (param2 / 16) nodes.
  • paramtype2 = "degrotate"
    • Only valid for "plantlike". The rotation of the node is stored in param2.
    • Values range 0 - 179. The value stored in param2 is multiplied by two to get the actual rotation in degrees of the node.
  • paramtype2 = "meshoptions"
    • Only valid for "plantlike". The value of param2 becomes a bitfield which can be used to change how the client draws plantlike nodes.
    • Bits 0, 1 and 2 form a mesh selector. Currently the following meshes are choosable:
      • 0 = a "x" shaped plant (ordinary plant)
      • 1 = a "+" shaped plant (just rotated 45 degrees)
      • 2 = a "*" shaped plant with 3 faces instead of 2
      • 3 = a "#" shaped plant with 4 faces instead of 2
      • 4 = a "#" shaped plant with 4 faces that lean outwards
      • 5-7 are unused and reserved for future meshes.
    • Bits 3 through 7 are optional flags that can be combined and give these effects:
      • bit 3 (0x08) - Makes the plant slightly vary placement horizontally
      • bit 4 (0x10) - Makes the plant mesh 1.4x larger
      • bit 5 (0x20) - Moves each face randomly a small bit down (1/8 max)
      • bits 6-7 are reserved for future use.
  • paramtype2 = "color"
    • param2 tells which color is picked from the palette. The palette should have 256 pixels.
  • paramtype2 = "colorfacedir"
    • Same as facedir, but with colors.
    • The first three bits of param2 tells which color is picked from the palette. The palette should have 8 pixels.
  • paramtype2 = "colorwallmounted"
    • Same as wallmounted, but with colors.
    • The first five bits of param2 tells which color is picked from the palette. The palette should have 32 pixels.
  • paramtype2 = "glasslikeliquidlevel"
    • Only valid for "glasslike_framed" or "glasslike_framed_optional" drawtypes.
    • param2 values 0-63 define 64 levels of internal liquid, 0 being empty and 63 being full.
    • Liquid texture is defined using special_tiles = {"modname_tilename.png"}

Nodes can also contain extra data. See [Node Metadata].

Node drawtypes

There are a bunch of different looking node types.

Look for examples in games/minimal or games/minetest_game.

  • normal
    • A node-sized cube.
  • airlike
    • Invisible, uses no texture.
  • liquid
    • The cubic source node for a liquid.
  • flowingliquid
    • The flowing version of a liquid, appears with various heights and slopes.
  • glasslike
    • Often used for partially-transparent nodes.
    • Only external sides of textures are visible.
  • glasslike_framed
    • All face-connected nodes are drawn as one volume within a surrounding frame.
    • The frame appearance is generated from the edges of the first texture specified in tiles. The width of the edges used are 1/16th of texture size: 1 pixel for 16x16, 2 pixels for 32x32 etc.
    • The glass 'shine' (or other desired detail) on each node face is supplied by the second texture specified in tiles.
  • glasslike_framed_optional
    • This switches between the above 2 drawtypes according to the menu setting 'Connected Glass'.
  • allfaces
    • Often used for partially-transparent nodes.
    • External and internal sides of textures are visible.
  • allfaces_optional
    • Often used for leaves nodes.
    • This switches between normal, glasslike and allfaces according to the menu setting: Opaque Leaves / Simple Leaves / Fancy Leaves.
    • With 'Simple Leaves' selected, the texture specified in special_tiles is used instead, if present. This allows a visually thicker texture to be used to compensate for how glasslike reduces visual thickness.
  • torchlike
    • A single vertical texture.
    • If placed on top of a node, uses the first texture specified in tiles.
    • If placed against the underside of a node, uses the second texture specified in tiles.
    • If placed on the side of a node, uses the third texture specified in tiles and is perpendicular to that node.
  • signlike
    • A single texture parallel to, and mounted against, the top, underside or side of a node.
  • plantlike
    • Two vertical and diagonal textures at right-angles to each other.
    • See paramtype2 = "meshoptions" above for other options.
  • firelike
    • When above a flat surface, appears as 6 textures, the central 2 as plantlike plus 4 more surrounding those.
    • If not above a surface the central 2 do not appear, but the texture appears against the faces of surrounding nodes if they are present.
  • fencelike
    • A 3D model suitable for a wooden fence.
    • One placed node appears as a single vertical post.
    • Adjacently-placed nodes cause horizontal bars to appear between them.
  • raillike
    • Often used for tracks for mining carts.
    • Requires 4 textures to be specified in tiles, in order: Straight, curved, t-junction, crossing.
    • Each placed node automatically switches to a suitable rotated texture determined by the adjacent raillike nodes, in order to create a continuous track network.
    • Becomes a sloping node if placed against stepped nodes.
  • nodebox
    • Often used for stairs and slabs.
    • Allows defining nodes consisting of an arbitrary number of boxes.
    • See [Node boxes] below for more information.
  • mesh
    • Uses models for nodes.
    • Tiles should hold model materials textures.
    • Only static meshes are implemented.
    • For supported model formats see Irrlicht engine documentation.
  • plantlike_rooted
    • Enables underwater plantlike without air bubbles around the nodes.
    • Consists of a base cube at the co-ordinates of the node plus a plantlike extension above with a height of param2 / 16 nodes.
    • The plantlike extension visually passes through any nodes above the base cube without affecting them.
    • The base cube texture tiles are defined as normal, the plantlike extension uses the defined special tile, for example: special_tiles = {{name = "default_papyrus.png", tileable_vertical = true}},

*_optional drawtypes need less rendering time if deactivated (always client-side).

Node boxes

Node selection boxes are defined using "node boxes".

A nodebox is defined as any of:

{
    -- A normal cube; the default in most things
    type = "regular"
}
{
    -- A fixed box (or boxes) (facedir param2 is used, if applicable)
    type = "fixed",
    fixed = box OR {box1, box2, ...}
}
{
    -- A variable height box (or boxes) with the top face position defined
    -- by the node parameter 'leveled = ', or if 'paramtype2 == "leveled"'
    -- by param2.
    -- Other faces are defined by 'fixed = {}' as with 'type = "fixed"'.
    type = "leveled",
    fixed = box OR {box1, box2, ...}
}
{
    -- A box like the selection box for torches
    -- (wallmounted param2 is used, if applicable)
    type = "wallmounted",
    wall_top = box,
    wall_bottom = box,
    wall_side = box
}
{
    -- A node that has optional boxes depending on neighbouring nodes'
    -- presence and type. See also `connects_to`.
    type = "connected",
    fixed = box OR {box1, box2, ...}
    connect_top = box OR {box1, box2, ...}
    connect_bottom = box OR {box1, box2, ...}
    connect_front = box OR {box1, box2, ...}
    connect_left = box OR {box1, box2, ...}
    connect_back = box OR {box1, box2, ...}
    connect_right = box OR {box1, box2, ...}
    -- The following `disconnected_*` boxes are the opposites of the
    -- `connect_*` ones above, i.e. when a node has no suitable neighbour
    -- on the respective side, the corresponding disconnected box is drawn.
    disconnected_top = box OR {box1, box2, ...}
    disconnected_bottom = box OR {box1, box2, ...}
    disconnected_front = box OR {box1, box2, ...}
    disconnected_left = box OR {box1, box2, ...}
    disconnected_back = box OR {box1, box2, ...}
    disconnected_right = box OR {box1, box2, ...}
    disconnected = box OR {box1, box2, ...} -- when there is *no* neighbour
    disconnected_sides = box OR {box1, box2, ...} -- when there are *no*
                                                  -- neighbours to the sides
}

A box is defined as:

{x1, y1, z1, x2, y2, z2}

A box of a regular node would look like:

{-0.5, -0.5, -0.5, 0.5, 0.5, 0.5},