OpenMiner/docs/lua-api-block.md

Lua API: Block

Example

mod:block {
	id = "myblock",    -- mandatory
	name = "My Block", -- mandatory
	tiles = "myblock.png",
}

Attributes

id

ID of the block. Mandatory field.

Example:

id = "cobblestone"

IDs are usually of the form mod:block but the mod: prefix is prepended automatically so it's not needed.

name

Label of the block. Mandatory field.

Example:

name = "Cobblestone"

This label is the name that will appear everywhere in the game.

tiles

This field can be either a single string, or a table of strings.

Example:

tiles = "myblock.png"
-- or
tiles = {"myblock_top.png", "myblock_bottom.png", "myblock_side.png"}

Table format:

// namely: West, East, South, North, Bottom, Top
{0, 0, 0, 0, 0, 0}, // for size = 1
{1, 1, 1, 1, 0, 0}, // for size = 2
{2, 2, 2, 2, 1, 0}, // for size = 3
{2, 3, 3, 3, 1, 0}, // for size = 4
{2, 3, 4, 4, 1, 0}, // for size = 5
{2, 3, 4, 5, 1, 0}, // for size = 6

The textures will be loaded from mods/<your-mod>/textures/blocks

Note: Currently, you can only use textures of the exact same size (16x16, 32x32) than the other block/item textures in the game.

harvest_requirements

Set which tools are more effective.

Note: This attribute would need more doc but it'll probably get removed soon.

hardness

Hardness of the block, affects mining speed.

Example:

hardness = 0.5

Default value is 1.0, any value under this will increase mining speed, and any value above will decrease mining speed.

is_opaque

Defines if the block let the light pass or not.

Example:

is_opaque = true -- this is the default value

is_light_source

Defines if the block is the light source or not.

Example:

is_light_source = false -- this is the default value

is_rotatable

Defines if the block should face the player when placed, like the furnace for example

Example:

is_rotatable = false -- this is the default value

bounding_box

Bounding box of the box.

Example:

bounding_box = {0, 0, 0, 1, 1, 1} -- this is default value

Format is {x, y, z, width, depth, height}. Note that OpenMiner uses Z axis as up.

The bounding box determines collisions with the block, as well as the selection box that will be displayed when looking at the block.

Note: This is what affects the temporary boundingbox draw type.

draw_type

Draw type of the block, see Draw types for more details.

Example:

draw_type = "solid" -- this is the default value

item_drop

Item stack that is given to the player when breaking the block.

Example:

item_drop = {
	id = "default:cobblestone",
	amount = 1
} -- this is the default drop of a 'default:cobblestone' block

color_multiplier

Color multiplier of the grayscale parts of the block texture.

Example:

color_multiplier = {1, 1, 1, 1} -- full white, this is the default value

Only the pure gray parts (red == green == blue) will be affected by this multiplier.

Draw types

The draw type changes how the block is rendered.

solid

This draw type is the default draw type of the blocks.

It renders a basic textured cube of size 1x1x1.

xshape

Draws two textured quads that form an X shape.

Useful for flora, tallgrass, mushrooms, etc...

leaves

Keep all the faces while drawing a block.

Especially useful for leaves.

liquid

This draw type doesn't do much yet.

Makes a single mesh with all the connected blocks of the same type in a chunk.

It will be rendered without back-face culling (this is why you can see water surface while being inside).

glass

Draw type used for glass-type blocks. Also works for portals.

Almost the same as the liquid draw type, except that back-face culling is enabled.

cactus

Using the bounding_box attribute, will draw a # shape instead of a cube.

Useful for cactus block.

boundingbox

NB: Temporary draw type.

Allow drawing a block of the size of the bounding_box.

Functions

on_block_placed

Parameters:

• pos (ivec3): position of the block
• world (World): instance of ServerWorld

on_block_activated

Parameters:

• pos (ivec3): position of the block
• player (Player): player that activated the block
• world (World): instance of the ServerWorld
• client (Client): client that activated the block
• server (Server): current server
• screen_width (u16): width of the screen
• screen_height (u16): height of the screen
• gui_scale (u8): current scaling setting

on_tick

Parameters:

• pos (ivec3): position of the block
• chunk (Chunk): current chunk
• world (World): instance of the ServerWorld