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.

Advertisement

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 basics

  • blocks.register(id, definition), items.register(...) and entities.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",
})
FieldDefaultWhat it does
namefrom the idthe name players see. "ruby_ore" becomes "Ruby Ore"
textureone file for every side, or a table of sides: all, top, bottom, side, front, or north, south, east, west
modela 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, resistance1.5, same as hardnesshow 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, toolLevelthe tool that mines it fastest (pickaxe, axe, shovel, hoe) and the tool it needs (wood, stone, iron, diamond)
requiresTooltrue if toolLevel is setwhen 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
light0how much light it gives off, 0 to 15. A torch is 14
friction0.6ice is 0.98, so you slide
speed, jump1, 1soul sand slows you with 0.4, honey stops jumps with 0.5
transparentfalsefor glass, leaves and anything else you can see through
collisiontruefalse lets you walk through it
flammablefalsefire 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
xp0experience when mined, a number or { min, max }
itemtruefalse 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
tagsMinecraft 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 } } },
})
FieldDefaultWhat it does
name, texture, modellike blocks. model is an item model .json
stack64how many fit in one slot, 1 to 99. Items with durability always stack to 1
durabilityhow many uses before it breaks
toolmakes it a tool. See below
foodmakes it food. See below
rarity"common"uncommon (yellow), rare (aqua) or epic (purple) name
glintfalsethe enchanted shine
fireResistantfalseit survives fire and lava, like netherite
handheldtrue for toolsheld in the hand like a tool
cooldown0seconds after onUse before it works again
tooltipa line or a list of lines under the name
tabdependsingredients for most items, tools_and_utilities for tools, combat for swords, food_and_drinks for food
tagsMinecraft 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, hoe or sword.
  • material: wood, stone, copper, iron, gold, diamond or netherite. It sets the mining speed, the blocks it can mine and how long it lasts.
  • damage and attackSpeed: 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: true lets you eat it when you are not hungry.
  • seconds: how long eating takes, 1.6 by default. drink = true makes it a drink.
  • effects: a list of { id = "speed", seconds = 10, level = 1, chance = 1 }. Any effect works, like regeneration, night_vision or jump_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.

FieldDefaultWhat it does
namefrom the id
texturethe 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
scale1makes the whole mob bigger or smaller, hitbox included
shadowhalf the widththe 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, armor10, 0.25, 0 or 3, 0a zombie has 20 health and 0.23 speed. Passive mobs do no damage
knockbackResistance, followRange0, 16from 0 to 1, and how far away it notices you
temptit follows players who hold this item, like cows follow wheat. An id, a #tag or a list
fireImmune, burnsInDaylight, translucentfalsetranslucent draws see-through parts of the texture, for ghosts
dropsan item id, one { item, min, max, chance } table, or a list of them. Looting adds more
xp2, or 5 if not passiveexperience when it dies
sounds{ ambient, hurt, death, step } with sound ids like "minecraft:entity.iron_golem.hurt"
eggrandom colorsthe spawn egg's two colors, { texture = "egg.png" } for your own picture, or false for no egg
tagsMinecraft 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), a pivot it turns around and a rotation in degrees (both { 0, 0, 0 } by default), and a parent (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), a size ({ 1, 1, 1 } by default), and a uv: the top-left corner of its faces on the texture, in the usual box layout ({ 0, 0 } by default). mirror = true flips the texture, and inflate grows the box a little without changing the texture.
  • animation makes a part move (parts stay still by default): head looks around, leg and arm swing while the mob walks (give one side phase = 180), spin turns, bob floats up and down, and wing flaps. speed speeds it up (1 by default), and phase shifts 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 in key is an item or a #tag, and a space is an empty slot.
  • shapeless: up to nine ingredients in any order.
  • smelting: a furnace recipe. seconds is 10 by default. blasting = true and smoking = true add blast furnace and smoker versions (twice as fast), and campfire = true a campfire one.
  • stonecutting: a stonecutter recipe.
  • count makes more than one, and id names 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:

EventWhat you getNotes
block_usee.block, e.x, e.y, e.z, e.face, e.hand, e.item, e.sneakingyou right-click a block. Can be cancelled
block_breake.block, e.x, e.y, e.zyou broke a block
item_usee.item, e.count, e.handyou right-click with an item. Can be cancelled
entity_interacte.entity, e.handyou right-click a mob. Can be cancelled
entity_attacke.entityyou 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.json with .ogg sounds, 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_use still 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.