OpenMiner/docs/lua-api-block.md

Lua API: Block

Example

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

Attributes

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.

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.

custom_param_bits

Allocate a certain number of bits in block param for custom data.

Note: Block param is limited to 16 bits.

Example:

custom_param_bits = 2 -- uses 2 bits

Default value is 0.

draw_offset

Draw offset of the block.

Example:

draw_offset = {0, 0, -1 / 16} -- used for crops

Note: The selection box will ignore this parameter.

draw_type

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

Example:

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

fog_color

Color of the fog drawn for players inside the block.

Example:

fog_color = {255, 0, 255}

fog_depth

Depth of the fog drawn for players inside the block.

Example:

fog_depth = 20

groups

Groups of the block. They can be used in recipes, and can also filter Lua-defined inventory widgets.

See Item#Attributes#groups for more details.

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.

harvest_requirements

Set a required tool type.

Example:

harvest_requirements = Capability.Pickaxe

Possible values:

• Capability.Pickaxe
• Capability.Shovel
• Capability.Axe

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.

inventory_image

Texture used for inventory rendering.

Example:

inventory_image = "cobblestone_item.png"

If you set this parameter the block will be displayed as an item in the inventory using this texture.

The texture is loaded from mods/<your-mod>/textures/items/.

is_collidable

Defines if the block can block the player or not.

Example:

is_collidable = true -- this is the default value

The default value changes to false if the draw type is liquid or xshape.

is_light_source

Defines if the block is the light source or not.

Example:

is_light_source = false -- this is the default value

is_opaque

Defines if the block let the light pass or not.

Example:

is_opaque = true -- 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

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

max_stack_size

Max amount of blocks in a stack.

Example:

max_stack_size = 64

If not defined, it defaults to the server config.

name

Label of the block. Mandatory field.

Example:

name = "Cobblestone"

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

placement_constraints

Constraints for the placement of the block.

Example:

placement_constraints = {
	-- ensure that the block below is farmland
	[{0, 0, -1}] = {
		block = "default:farmland",
		is_whitelist = true
	}
}

states

Optional table containing block state definitions.

Example:

mod:block {
	id = "default:seeds",
	label = "Seeds",
	draw_type = "xshape",
	inventory_image = "seeds_wheat.png",
	hardness = 0,

	tiles = "wheat_stage_0.png",
	bounding_box = {0, 0, 0, 1, 1, 1.0 / 16.0},

	states = {
		{ tiles = "wheat_stage_1.png", bounding_box = {0, 0, 0, 1, 1, 3.0 / 16.0}, },  -- 1
		{ tiles = "wheat_stage_2.png", bounding_box = {0, 0, 0, 1, 1, 5.0 / 16.0}, },  -- 2
		{ tiles = "wheat_stage_3.png", bounding_box = {0, 0, 0, 1, 1, 8.0 / 16.0}, },  -- 3
		{ tiles = "wheat_stage_4.png", bounding_box = {0, 0, 0, 1, 1, 10.0 / 16.0}, }, -- 4
		{ tiles = "wheat_stage_5.png", bounding_box = {0, 0, 0, 1, 1, 12.0 / 16.0}, }, -- 5
		{ tiles = "wheat_stage_6.png", bounding_box = {0, 0, 0, 1, 1, 14.0 / 16.0}, }, -- 6
		{ tiles = "wheat_stage_7.png", bounding_box = {0, 0, 0, 1, 1, 1}, },           -- 7
	},
}

States, when active, will override default attributes for the block.

Some attributes are not handled, mainly:

• groups
• id
• is_rotatable
• states
• tick_probability
• tick_randomly
• and all the callbacks

To get the current state of a block:

-- if you already have 'block'
local block_param = world:get_data(pos.x, pos.y, pos.z)
local current_state = block:param():get_param(BlockParamType.State, block_param)
-- if you don't
local current_state = world:get_block_state(pos.x, pos.y, pos.z):id()

To set the current state of a block:

local my_new_state = 5
-- if you already have 'block'
local block_param = world:get_data(pos.x, pos.y, pos.z)
local new_param = block:param():set_param(BlockParamType.State, block_param, my_new_state)
world:set_data(pos.x, pos.y, pos.z, new_param)
-- if you don't
world:set_block_state(pos.x, pos.y, pos.z, my_new_state)

tick_probability

Probability to call the on_tick function when tick_randomly is enabled.

Example:

tick_probability = 0.5 -- 50%

tick_randomly

Whether or not the block on_tick function is executed randomly.

See also tick_probability.

Example:

tick_randomly = true

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
{3, 2, 3, 3, 1, 0}, // for size = 4
{3, 2, 4, 4, 1, 0}, // for size = 5
{3, 2, 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) as the other block/item textures in the game.

Draw types

The draw type changes how the block is rendered.

boundingbox

NB: Temporary draw type.

Allow drawing a block of the size of the bounding_box.

cactus

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

Useful for cactus block.

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.

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).

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...

Functions

on_block_activated

Parameters:

• pos (ivec3): position of the block
• block (ServerBlock): block definition
• player (ServerPlayer): player that activated the block
• world (ServerWorld): instance of the world
• client (Client): client that activated the block
• server (Server): current server

on_block_destroyed

Parameters:

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

on_block_placed

Parameters:

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

on_tick

Parameters:

• pos (ivec3): position of the block
• block (ServerBlock): block definition
• chunk (ServerChunk): current chunk
• world (ServerWorld): instance of the world