Skip to content
Download

Custom items (tools, food, usable items)

Status: Implemented for items backed by a vanilla item, with their own model, name and use behaviour. Setting data components from code (durability, tool rules, food values, equipment) is Planned: today a tool, armour piece or food behaves like the vanilla item it is backed by.

Goal: a Ruby Pickaxe (mines like a diamond pickaxe), a Ruby Apple (eats like a golden apple) and a Healing Crystal that heals on right-click.

Language: Lua, with the C++ crystal at the end. APIs: Items and item stacks, Players.

How mod items work

A mod item is a stack of its base item (vanilla_fallback) with your id, model and name on top. Everything else (durability, mining speed, food, enchanting, attack damage) comes from the base item. So pick the base whose behaviour you want.

1. Register the items

cl.on("lifecycle.register", function()
  cl.items.register{ id = "ruby_pickaxe", vanilla_fallback = "minecraft:diamond_pickaxe", max_stack_size = 1 }
  cl.items.register{ id = "ruby_apple", vanilla_fallback = "minecraft:golden_apple" }
  cl.items.register{
    id = "healing_crystal",
    vanilla_fallback = "minecraft:amethyst_shard",
    max_stack_size = 16,
    behavior = {
      use = function(ctx)
        local player = ctx.entity
        if player.health >= 20 then return end          -- nothing to heal: let the base item act
        player:set_health(20)
        player:held_item(ctx.hand):shrink(1)            -- uses one up (not in creative mode)
        player:send_action_bar("You feel better.")
        return "success"
      end,
    },
  }
end)

2. Assets

For each item, assets/my_mod/items/<name>.json, models/item/<name>.json, textures/item/<name>.png and a lang entry:

{ "model": { "type": "minecraft:model", "model": "my_mod:item/ruby_pickaxe" } }

{ "parent": "minecraft:item/handheld", "textures": { "layer0": "my_mod:item/ruby_pickaxe" } }

{
  "item.my_mod.ruby_pickaxe": "Ruby Pickaxe",
  "item.my_mod.ruby_apple": "Ruby Apple",
  "item.my_mod.healing_crystal": "Healing Crystal"
}

Tools use item/handheld as the parent (held like a tool); most other items use item/generated.

3. Get them into the game

A recipe in your data pack (datapack/my_mod/recipe/ruby_pickaxe.json), with mod items as ingredients and result:

{
  "type": "minecraft:crafting_shaped",
  "category": "equipment",
  "pattern": ["RRR", " S ", " S "],
  "key": { "R": "my_mod:ruby", "S": "minecraft:stick" },
  "result": { "id": "my_mod:ruby_pickaxe", "count": 1 }
}

Set creative_tab (for example "minecraft:tools_and_utilities") to show the item in that creative tab. Or give them out:

The Healing Crystal in C++

void on_register() override {
    cl_item_desc d = CL_ITEM_DESC_INIT;
    d.id = CL_STR("my_mod:healing_crystal");
    d.vanilla_fallback = CL_STR("minecraft:amethyst_shard");
    d.max_stack_size = 16;
    clight::registry::item(d, {.use = [](const cl_item_ctx& c, cl_interaction_result& out) {
        clight::Entity player = c.entity;
        if (player.health() >= 20.0f) return CL_OVERRIDE_CALL_ORIGINAL;
        player.set_health(20.0f);
        player.inventory_consume(c.hand == CL_HAND_OFF ? 40 : player.selected_slot(), 1);
        player.send_action_bar("You feel better.");
        out = CL_RESULT_SUCCESS;
        return CL_OVERRIDE_HANDLED;
    }});
}

Planned

Durability, tool rules, food values, equipment slots and attribute modifiers set from code (data components), tooltips, more behaviour entries (use on a block or entity, finish using, inventory tick) and custom creative tabs.