Build a mod
Blocks, items and mobs
Add your own blocks, items, tools, food and mobs to the game, with textures, drops, crafting recipes and your own mob models.
Mods can add new things to the game: blocks you can place and mine, items, tools and food, mobs with their own look, and the recipes that make them. They show up in the creative inventory, work with /give and /summon, and save with your world like everything else.
Blocks, items and mobs work in your own worlds: singleplayer, and LAN worlds you open. Servers do not know about them. See Where it works.
Your first block
Make a 16x16 PNG, put it in your mod's zip as textures/ruby_block.png, and register the block in main.lua:
blocks.register("ruby_block", {
name = "Block of Ruby",
texture = "textures/ruby_block.png",
hardness = 5,
tool = "pickaxe",
toolLevel = "iron",
sound = "metal",
})
Install the mod, then reload the page. Open a world in Creative and the Block of Ruby is in the Building Blocks tab. If your mod's id is gems, the block's full id is gems:ruby_block, so /give @s gems:ruby_block and /setblock ~ ~ ~ gems:ruby_block work too.
The game adds blocks, items and mobs when it starts. When you install a mod, turn one on, or add a new block while you are playing, reload the page to get it. A message tells you when you need to.
The basics
blocks.register(id, definition),items.register(...)andentities.register(...)give back the full id,"<mod id>:<id>". Ids use lowercase letters, digits and_.- Register everything in
main.lua, while your mod loads. - Inside a definition, an id without a namespace means your own block or item when your mod registers one with that name, and Minecraft's otherwise. So
"ruby"is your ruby and"stick"is a normal stick. Tags start with#, like"#minecraft:planks". - Textures are PNG files in your zip, 16x16 for blocks and items. You can also use Minecraft's own textures, like
"minecraft:block/stone"or"minecraft:item/apple". - See-through pixels just work. For glass-like blocks also set
transparent = true, so the blocks behind them still show. - A typo in a field name stops your mod with a message that says what is wrong, like
blocks.register("ruby_ore"): unknown field hardnes. Check the mod's Log.
Blocks
blocks.register("ruby_ore", {
name = "Ruby Ore",
texture = "textures/ruby_ore.png",
hardness = 3,
tool = "pickaxe",
toolLevel = "iron",
drops = { item = "ruby", min = 1, max = 2, fortune = true, silkTouch = true },
xp = { 3, 7 },
tab = "natural_blocks",
})
| Field | Default | What it does |
|---|---|---|
name | from the id | the name players see. "ruby_ore" becomes "Ruby Ore" |
texture | one file for every side, or a table of sides: all, top, bottom, side, front, or north, south, east, west | |
model | a block model .json from your zip, instead of texture | |
shape | "cube" | "cross" for plants and flowers: you can walk through it and it breaks at once |
rotate | "none" | "horizontal" turns to face you like a furnace (give it a front texture). "axis" lies along the face you click, like a log |
hardness, resistance | 1.5, same as hardness | how long it takes to mine, and how well it stands up to explosions. Stone is 1.5 and 6, obsidian 50 and 1200, -1 can never be mined |
tool, toolLevel | the tool that mines it fastest (pickaxe, axe, shovel, hoe) and the tool it needs (wood, stone, iron, diamond) | |
requiresTool | true if toolLevel is set | when true, mining it without the right tool drops nothing |
sound | "stone" | stone wood gravel grass metal glass wool sand snow ladder anvil slime_block honey_block coral_block bamboo netherrack nether_bricks bone_block amethyst deepslate copper mud moss sculk cherry_wood chain lantern crop vine calcite tuff iron resin |
light | 0 | how much light it gives off, 0 to 15. A torch is 14 |
friction | 0.6 | ice is 0.98, so you slide |
speed, jump | 1, 1 | soul sand slows you with 0.4, honey stops jumps with 0.5 |
transparent | false | for glass, leaves and anything else you can see through |
collision | true | false lets you walk through it |
flammable | false | fire spreads to it and burns it away |
drops | "self" | "none", an item id, or { item, min, max, fortune, silkTouch }. With silkTouch, a Silk Touch tool drops the block itself |
xp | 0 | experience when mined, a number or { min, max } |
item | true | false gives the block no item, so it can only be placed with commands |
tab | "building_blocks" | the creative tab, or "none" to keep it out of the creative inventory |
tags | Minecraft block tags, like { "minecraft:climbable" } to make it a ladder or { "minecraft:logs" } | |
onUse(e), onBreak(e) | your code when you right-click or break the block (see Make things happen) |
The creative tabs are building_blocks, colored_blocks, natural_blocks, functional_blocks, redstone_blocks, tools_and_utilities, combat, food_and_drinks, ingredients, spawn_eggs and op_blocks.
Items
items.register("ruby", { name = "Ruby", texture = "textures/ruby.png" })
items.register("ruby_sword", {
name = "Ruby Sword",
texture = "textures/ruby_sword.png",
tool = { type = "sword", material = "diamond", damage = 8 },
rarity = "uncommon",
})
items.register("ruby_apple", {
name = "Ruby Apple",
texture = "textures/ruby_apple.png",
glint = true,
tooltip = "Fizzes with energy",
food = { nutrition = 6, saturation = 1.2, alwaysEat = true, effects = { { id = "speed", seconds = 30, level = 2 } } },
})
| Field | Default | What it does |
|---|---|---|
name, texture, model | like blocks. model is an item model .json | |
stack | 64 | how many fit in one slot, 1 to 99. Items with durability always stack to 1 |
durability | how many uses before it breaks | |
tool | makes it a tool. See below | |
food | makes it food. See below | |
rarity | "common" | uncommon (yellow), rare (aqua) or epic (purple) name |
glint | false | the enchanted shine |
fireResistant | false | it survives fire and lava, like netherite |
handheld | true for tools | held in the hand like a tool |
cooldown | 0 | seconds after onUse before it works again |
tooltip | a line or a list of lines under the name | |
tab | depends | ingredients for most items, tools_and_utilities for tools, combat for swords, food_and_drinks for food |
tags | Minecraft item tags | |
onUse(e) | your code when you right-click with the item |
Tools
tool = { type = "pickaxe", material = "iron" } makes a tool that mines and hits like that tool made of that material.
type:pickaxe,axe,shovel,hoeorsword.material:wood,stone,copper,iron,gold,diamondornetherite. It sets the mining speed, the blocks it can mine and how long it lasts.damageandattackSpeed: the numbers the tooltip shows. Leave them out for the usual values.durability: uses before it breaks, instead of the material's.
Food
food = { nutrition = 4, saturation = 0.3 } makes an item you can eat.
nutrition: how many half drumsticks it fills, 0 to 20.saturation: how long you stay full. Bread is 0.6, golden carrots 1.2.alwaysEat:truelets you eat it when you are not hungry.seconds: how long eating takes, 1.6 by default.drink = truemakes it a drink.effects: a list of{ id = "speed", seconds = 10, level = 1, chance = 1 }. Any effect works, likeregeneration,night_visionorjump_boost.
Mobs
entities.register("ruby_golem", {
name = "Ruby Golem",
texture = "textures/ruby_golem.png",
model = "minecraft:zombie",
behavior = "neutral",
health = 30,
damage = 5,
tempt = "ruby",
drops = { item = "ruby", min = 1, max = 3 },
egg = { "#8A8A8A", "#C8102E" },
})
Every mob gets a spawn egg in the Spawn Eggs tab, unless you set egg = false. You can also summon it with /summon gems:ruby_golem, or from your mod with commands.run. Mobs do not spawn on their own yet.
| Field | Default | What it does |
|---|---|---|
name | from the id | |
texture | the mob's skin. Required | |
model | "minecraft:zombie" | the shape: any Minecraft mob, like "minecraft:pig", "minecraft:cow" or "minecraft:skeleton", painted with your texture. Or your own model |
size | { 0.6, 1.8 } | width and height of its hitbox, in blocks |
scale | 1 | makes the whole mob bigger or smaller, hitbox included |
shadow | half the width | the size of its shadow |
behavior | "passive" | passive wanders and runs away when hit. neutral fights back. hostile hunts players, disappears when you go far away and stays away in Peaceful |
health, speed, damage, armor | 10, 0.25, 0 or 3, 0 | a zombie has 20 health and 0.23 speed. Passive mobs do no damage |
knockbackResistance, followRange | 0, 16 | from 0 to 1, and how far away it notices you |
tempt | it follows players who hold this item, like cows follow wheat. An id, a #tag or a list | |
fireImmune, burnsInDaylight, translucent | false | translucent draws see-through parts of the texture, for ghosts |
drops | an item id, one { item, min, max, chance } table, or a list of them. Looting adds more | |
xp | 2, or 5 if not passive | experience when it dies |
sounds | { ambient, hurt, death, step } with sound ids like "minecraft:entity.iron_golem.hurt" | |
egg | random colors | the spawn egg's two colors, { texture = "egg.png" } for your own picture, or false for no egg |
tags | Minecraft entity tags, like { "minecraft:undead" } | |
onInteract(e), onAttack(e) | your code when you right-click or hit the mob |
Your own mob model
Instead of a Minecraft shape, model can be a list of parts made of boxes. It uses the same units as Blockbench's "Modded Entity" models: pixels (16 to a block), y goes down, and y = 24 is the ground.
model = {
textureWidth = 64,
textureHeight = 32,
parts = {
{ name = "body", cubes = { { origin = { -4, 0, -2 }, size = { 8, 12, 4 }, uv = { 16, 16 } } } },
{ name = "head", animation = "head",
cubes = { { origin = { -4, -8, -4 }, size = { 8, 8, 8 }, uv = { 0, 0 } } } },
{ name = "right_leg", pivot = { -1.9, 12, 0 }, animation = "leg",
cubes = { { origin = { -2, 0, -2 }, size = { 4, 12, 4 }, uv = { 0, 16 } } } },
{ name = "left_leg", pivot = { 1.9, 12, 0 }, animation = "leg", phase = 180,
cubes = { { origin = { -2, 0, -2 }, size = { 4, 12, 4 }, uv = { 0, 16 }, mirror = true } } },
},
}
- Each part needs a
name. Everything else is optional:cubes(none by default), apivotit turns around and arotationin degrees (both{ 0, 0, 0 }by default), and aparent(a part listed before it) to make it move with that part, like a hat on a head. - Each cube has an
origin(its corner, measured from the pivot,{ 0, 0, 0 }by default), asize({ 1, 1, 1 }by default), and auv: the top-left corner of its faces on the texture, in the usual box layout ({ 0, 0 }by default).mirror = trueflips the texture, andinflategrows the box a little without changing the texture. animationmakes a part move (parts stay still by default):headlooks around,legandarmswing while the mob walks (give one sidephase = 180),spinturns,bobfloats up and down, andwingflaps.speedspeeds it up (1 by default), andphaseshifts it in degrees (0 by default).
Minecraft shapes like "minecraft:pig" already move their head and legs.
Recipes
recipes.shaped({ pattern = { "RRR", " S ", " S " }, key = { R = "ruby", S = "stick" }, result = "ruby_pickaxe" })
recipes.shapeless({ ingredients = { "ruby_block" }, result = "ruby", count = 9 })
recipes.smelting({ input = "ruby_ore", result = "ruby", xp = 1, blasting = true })
recipes.stonecutting({ input = "ruby_block", result = "ruby_tiles", count = 4 })
shaped: up to three rows of up to three letters. Each letter inkeyis an item or a#tag, and a space is an empty slot.shapeless: up to nine ingredients in any order.smelting: a furnace recipe.secondsis 10 by default.blasting = trueandsmoking = trueadd blast furnace and smoker versions (twice as fast), andcampfire = truea campfire one.stonecutting: a stonecutter recipe.countmakes more than one, andidnames the recipe if you want to.recipes.add(id, table)adds any Minecraft recipe, written as a Lua table in the same shape as the game's recipe files.
Recipes load when you open a world, and they show up in the recipe book like any other.
Make things happen
onUse, onBreak, onInteract and onAttack run when you click a block, item or mob. They run on your own computer, so other players and mobs do not set them off.
To change the world from your code, run a Minecraft command with commands.run. It runs in your own world, as you, with operator rights even when cheats are off. Because it can do anything an operator can, your mod has to ask for it: add "commands" to permissions in metadata.json, or -- permissions: commands to a one-file mod, and players see it in the install prompt (see Permissions).
items.register("speed_charm", {
name = "Speed Charm",
texture = "textures/charm.png",
cooldown = 10,
onUse = function(e)
commands.run("effect give @s minecraft:speed 10 1")
end,
})
blocks.register("ruby_lamp", {
name = "Ruby Lamp",
texture = "textures/ruby_lamp.png",
light = 15,
onUse = function(e)
commands.run(string.format("particle minecraft:flame %d %d %d 0.3 0.3 0.3 0.02 20", e.x, e.y + 1, e.z))
end,
})
@s and ~ ~ ~ mean you. Pass a function as the second argument to find out how it went: commands.run("give @s gems:ruby 16", function(ok, output) ... end). output is the text the command printed. On a server, commands.run does nothing and gives back false and a message.
The callbacks get the same table as these events, which also fire for normal Minecraft blocks, items and mobs:
| Event | What you get | Notes |
|---|---|---|
block_use | e.block, e.x, e.y, e.z, e.face, e.hand, e.item, e.sneaking | you right-click a block. Can be cancelled |
block_break | e.block, e.x, e.y, e.z | you broke a block |
item_use | e.item, e.count, e.hand | you right-click with an item. Can be cancelled |
entity_interact | e.entity, e.hand | you right-click a mob. Can be cancelled |
entity_attack | e.entity | you hit a mob. Can be cancelled |
e.hand is "main" or "off", and e.entity has the same fields as the mobs from world.entities.
Resource and data files
For anything the fields above do not cover, put Minecraft's own file formats in your zip:
- Files in
assets/<namespace>/load like a resource pack when the game starts: block and item models,sounds.jsonwith.oggsounds, language files and textures. - Files in
data/<namespace>/load like a data pack when you open a world: loot tables, tags, advancements and more.
For example, a block with model = "models/fancy.json" can use textures you put in assets/<mod id>/textures/block/.
Where it works
- Singleplayer and LAN worlds you open: everything works.
- LAN worlds you join: you need the same mods as the host. Without them you are disconnected when their blocks come into view.
- Servers: the server does not know your blocks, items or mobs, so the creative inventory hides them. Events like
block_usestill work for normal blocks. - Removing a mod: whatever it added leaves your worlds. Its blocks turn into air, and its items and mobs disappear when those places load again. Back up a world before you remove a mod it uses.
- Minecraft only has room for a limited number of extra block states, and all your mods share it: 402 on 26.2 and 29,813 on 26.3. A block with
rotate = "horizontal"uses 4, one with"axis"uses 3, and any other block uses 1. When there is no room left, the block's mod stops with a message that says how many fit.



