Lua API: Item

Example

mod:item {
    id = "myitem",    -- mandatory
    name = "My Item", -- mandatory
    tiles = "myitem.png",
}

Attributes

effective_on

List of groups or block string IDs on which that item is effective when mining.

Example:

effective_on = {
    "group:om_material_dirt",
    "group:om_material_sand"
}

groups

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

Each group must be set to 1 if present. Default value for each group is 0, and it cannot exceeds 65535.

Example:

groups = {
    om_fuel = 200 -- example burn time for a coal item
}

Engine groups always start with om_ prefix. If you create your own groups, please prefix them with something to let people know that the group comes from your mod.

Available engine groups:

  • om_fuel: used in default:furnace and MouseWidgetItem, the value represents the burn time
  • om_material_dirt/sand/wood/stone: these groups are not used in the engine, but it's nice to use them if you can

harvest_capability

For a tool, set which type of blocks it's allowed to mine.

Example:

harvest_capability = Capability.Pickaxe

Possible values:

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

id

ID of the item. Mandatory field.

Example:

id = "stick"

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

mining_speed

For a tool, speed at which it mines the block.

Example:

mining_speed = 1 -- this is the default value

max_stack_size

Max amount of items in a stack.

Example:

max_stack_size = 64

If not defined, it defaults to the server config.

name

Label of the item. Mandatory field.

Example:

name = "Stick"

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

tiles

Texture of the item.

Example:

tiles = "myblock.png"

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

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

Functions

on_item_activated

Parameters:

  • pos (ivec3): position of the targeted block
  • block (Block): definition of the targeted block
  • player (Player): player that activated the item
  • world (World): instance of the ServerWorld
  • client (Client): client that activated the item
  • server (Server): current server