OpenMiner/docs/lua-api-mod.md

Lua API: Mod API Overview

Intrduction

Mods are folders and they should contain at least two files:

• init.lua: your code
• config.lua: mod config (name, depedencies)

They are located in mods folder.

Mod config

Here is an example of configuration:

mod_config = {
	id = "creative_inventory",

	dependencies = {"*default"}
}

The * before default means it's an optional dependency.

How to use this API

You can create a mod using this function:

openminer.mod_loader:register_mod("mod_name")

Mod name should match this regex: ^[a-zA-Z0-9_]+$

Everytime you define an id for a mod element, this name will be prepended to it. For example, myitem will become mymod:myitem.

The name can't be group because this namespace is already used by the engine.

Example

local mod = openminer.mod_loader:register_mod("mymod")

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

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

mod:crafting_recipe {
	result = {
		id = "mymod:myblock",
		amount = 1
	},

	pattern = {
		"###",
		"# #",
		"###"
	},

	keys = {["#"] = "default:cobblestone"}
}

mod:smelting_recipe {
	input = {id = "mymod:myitem", amount = 1},
	output = {id = "mymod:myblock", amount = 1}
}

Functions

id

Returns the string ID of the mod.

path

Returns the path of the mod, relative to current working directory.

Note: In callbacks like on_block_activated, the mod object may be invalid. You'll need to create a local variable at the beginning of the file:

local modpath = mod:path()

Utility functions

despawn_entity

Despawn an entity.

Example:

mod:despawn_entity(entity)

NB: entity is an EntityWrapper instance here. Currently, only on_collision entity callback can use it.

give_item_stack

Give an item stack to a player.

Example:

local items_left = mod:give_item_stack(player, item_stack)

This function returns an ItemStack containing the items it couldn't place into player's inventory.

spawn_entity

Spawn an entity.

Example:

mod:spawn_entity("default:item_drop", {
	position = {pos.x + 0.5, pos.y + 0.5, pos.z + 0.5},
	dimension = world:dimension():id(),

	item_stack = {block:get_item_drop():item():string_id(), block:get_item_drop():amount()}
})

See entity page for more information about the available fields in the table.

Registration functions

option

Defines a config option.

Example:

mod:option("use_item_drops", false);

See this page for more details.

Other functions

• block
• biome
• dimension
• entity
• item
• key
• recipe
• sky
• tree