CustomItem

A vanilla item with its own look and name. It writes the model drawn from its texture, the item model that its item_model component names and its name in the lang files. Its name then stands for the base item with those components wherever an item stack goes: recipe results, loot entries and ${...} in commands.

CustomItem name {
  base = ...
}

CustomItem is a Blueprint in the prelude: it is written in MMS, and every project has it.

Fields

base

Id<item>

The vanilla item this one is made from. It keeps the base item's behaviour; recipes and item tests that ask for an item id match the base.

nameoptional

LangText?

The item's name: text for en_us, or one text per language such as { en_us = "Ember Shard", de_de = "Glutsplitter" }. It becomes an item.<namespace>.<name> entry in the lang files and the item's item_name component.

textureoptional

Texture?

The item's picture, usually Texture("art/name.png"), which is copied to textures/item/<name>.png. It makes a flat item model, like most vanilla items.

parentoptional

Id<model>?

The parent of the model drawn from texture: item/generated (the default) for flat items, item/handheld for tools held like a sword.

modeloptional

Id<model>?

An existing model to show instead of one drawn from texture, such as a Model declared in the project.

item_modeloptional

ItemModel?

An item model to use instead of the generated one: the id of an ItemModel, or its body, such as { model = Select(...) } for an item that changes its look.

componentsdefault {}

DataComponentPatch

More item components, such as max_stack_size or rarity. Every use of the item gets them.

consume_on_useoptional

int?

How many of the item each right-click use takes from the stack, paid once per press by on_right_click, on_use_on_block or on_right_click_entity.

damage_on_useoptional

int?

How much durability each right-click use costs, paid like consume_on_use. The item needs a max_damage component, and gets max_stack_size = 1 unless it sets one. When the durability runs out the item breaks, and on_break runs.

on_right_clickoptional

Function?

A Function without parameters to run, as and at the player, when they right-click with the item: once per press, not again while the button is held. When the item also has on_use_on_block or on_right_click_entity, a press that runs one of those does not run this one too, so this is the click at anything else, such as the air.

on_hold_right_clickoptional

Function?

A Function without parameters to run, as and at the player, on every tick they hold right click with the item.

on_use_on_blockoptional

Function?

A Function without parameters to run when a player right-clicks a block with the item, once per press: as the player, positioned at the centre of the block.

on_right_click_entityoptional

Function?

A Function without parameters to run when a player right-clicks an entity with the item, once per press: as the player, at the entity, which has the tag mms_target while it runs.

on_hitoptional

Function?

A Function without parameters to run, as and at the player, when they hurt an entity while holding the item in their main hand.

on_killoptional

Function?

A Function without parameters to run, as and at the player, when they kill an entity while holding the item in their main hand.

on_consumeoptional

Function?

A Function without parameters to run, as and at the player, when they finish eating or drinking the item. The item needs a consumable component, or a base item that is food or a potion. It cannot be combined with the right-click hooks.

on_pickupoptional

Function?

A Function without parameters to run, as and at the player, when they pick the item up from the ground.

on_breakoptional

Function?

A Function without parameters to run, as and at the player, when the item runs out of durability and breaks. The item needs durability: a tool, weapon or armor base, or a max_damage component.

on_projectile_hit_blockoptional

Function?

A Function without parameters to run when an arrow hits a block: an arrow shot from the item, for a bow or crossbow base, or the arrow that is the item, for an arrow, tipped_arrow or spectral_arrow base. It runs as the arrow, at the point it hit; execute on origin is the shooter.

on_projectile_hit_entityoptional

Function?

A Function without parameters to run when an arrow hurts an entity: an arrow shot from the item, for a bow or crossbow base, or the arrow that is the item, for an arrow, tipped_arrow or spectral_arrow base. It runs as and at the entity hit; execute on attacker is the shooter.

on_projectile_landoptional

Function?

A Function without parameters to run where a thrown splash or lingering potion that is the item lands, whatever it hits. It runs at the spot, as a marker that is removed afterwards. Needs a splash_potion or lingering_potion base.

What its name stands for

Where one of these types is expected, the declaration's name means:

ItemStackTemplate

In a recipe result, a loot entry, or ${...} in a command: the base item with the custom item's components.

ItemStack

LootPoolEntry

Id<item>

A CustomItem used where the game takes a plain item id, such as a recipe ingredient or an item tag. It stands for its base item there, so it also matches the base item without the custom components.