CustomItem

Namespace Mc.Scripting.Content · Kind class (sealed)

public sealed class CustomItem

A custom item: a vanilla item the client already knows (the base item decides the id the client sees and the behaviour class) carrying data components that make it a different item: custom_data (the id, found again with ItemStack.CustomId), item_model (the look, from a resource pack), a name, lore, a stack size and a rarity. No client mod is needed. Register it with ItemRegistry.Register, hand out stacks with CustomItem.CreateStack.

Remarks

Choose an inert base item (minecraft:paper, minecraft:stick, minecraft:amethyst_shard): the vanilla behaviour of the base item still happens unless a use handler cancels it. Stacks keep their id when the plugin is unloaded; they behave like the base item until it is back.

Constructors

Member	Description
CustomItem(string id, string baseItem)	Creates a definition.

Constructor

public CustomItem(string id, string baseItem)

Creates a definition.

Parameters

Name	Type	Description
id	string	The id of the item, "myplugin:ruby".
baseItem	string	The vanilla item it is built on, "minecraft:paper".

Properties

Member	Description
string BaseItem { get; }	The vanilla base item.
int CooldownTicks { get; }	Ticks a player waits between two uses (0 for none).
Component? DisplayName { get; }	The display name.
bool? HasGlint { get; }	The enchantment glint (null: the item’s own).
string Id { get; }	The id.
IReadOnlyList<Component> LoreLines { get; }	The lore lines.
int MaxStackSize { get; }	The maximum stack size, 0 for the base item’s own.
string? ModelId { get; }	The item model id (an item definition of the resource pack), or null for the base item’s own.
string? PlacesBlock { get; }	The id of the custom block the item places when used on a block, or null.
ItemRarity? Rarity { get; }	The rarity, null for the base item’s own.
Action<ItemUseContext>? UseHandler { get; }	The handler called when a player uses the item in the air or on a block.
Action<ItemUseContext>? UseOnHandler { get; }	The handler called when a player uses the item on a block.

BaseItem

public string BaseItem { get; }

The vanilla base item.

CooldownTicks

public int CooldownTicks { get; }

Ticks a player waits between two uses (0 for none).

DisplayName

public Component? DisplayName { get; }

The display name.

HasGlint

public bool? HasGlint { get; }

The enchantment glint (null: the item’s own).

Id

public string Id { get; }

The id.

LoreLines

public IReadOnlyList<Component> LoreLines { get; }

The lore lines.

MaxStackSize

public int MaxStackSize { get; }

The maximum stack size, 0 for the base item’s own.

ModelId

public string? ModelId { get; }

The item model id (an item definition of the resource pack), or null for the base item’s own.

PlacesBlock

public string? PlacesBlock { get; }

The id of the custom block the item places when used on a block, or null.

Rarity

public ItemRarity? Rarity { get; }

The rarity, null for the base item’s own.

UseHandler

public Action<ItemUseContext>? UseHandler { get; }

The handler called when a player uses the item in the air or on a block.

UseOnHandler

public Action<ItemUseContext>? UseOnHandler { get; }

The handler called when a player uses the item on a block.

Methods

Member	Description
CustomItem Cooldown(int ticks)	Makes a player wait between two uses: further uses are ignored (cancelled) during the cooldown.
ItemStack CreateStack(int count = 1)	A stack of the item with every component of the definition.
CustomItem Glint(bool glint = true)	Forces the enchantment glint on or off.
CustomItem Lore(params Component[] lines)	Sets the lore lines.
bool Matches(ItemStack stack)	Whether a stack is an instance of this item (its ItemStack.CustomId is the id).
CustomItem MaxStack(int max)	Sets the maximum stack size.
CustomItem Model(string modelId)	Sets the item model (minecraft:item_model).
CustomItem Name(Component name)	Sets the display name (minecraft:item_name: not italic, replaced by an anvil rename).
CustomItem OnUse(Action<ItemUseContext> handler)	Sets what happens when a player uses the item (right click in the air or on a block).
CustomItem OnUseOn(Action<ItemUseContext> handler)	Sets what happens when a player uses the item on a block (after {{cref:M:Mc.Scripting.Content.CustomItem.OnUse(System.Action{Mc.Scripting.Content.ItemUseContext})}}).
CustomItem Places(CustomBlock block)	Makes the item place a custom block against the clicked face (and use up one item).
CustomItem WithRarity(ItemRarity rarity)	Sets the rarity.

Cooldown

public CustomItem Cooldown(int ticks)

Makes a player wait between two uses: further uses are ignored (cancelled) during the cooldown.

Parameters

Name	Type	Description
ticks	int	The wait in ticks (20 = 1 second).

Returns CustomItem: This definition.

CreateStack

public ItemStack CreateStack(int count = 1)

A stack of the item with every component of the definition.

Parameters

Name	Type	Description
count	int = 1	The stack size.

Returns ItemStack: The stack.

Glint

public CustomItem Glint(bool glint = true)

Forces the enchantment glint on or off.

Parameters

Name	Type	Description
glint	bool = true	Whether the item glows.

Returns CustomItem: This definition.

Lore

public CustomItem Lore(params Component[] lines)

Sets the lore lines.

Parameters

Name	Type	Description
lines	params Component[]	The lines.

Returns CustomItem: This definition.

Matches

public bool Matches(ItemStack stack)

Whether a stack is an instance of this item (its ItemStack.CustomId is the id).

Parameters

Name	Type	Description
stack	ItemStack	The stack.

Returns bool: True when it is.

MaxStack

public CustomItem MaxStack(int max)

Sets the maximum stack size.

Parameters

Name	Type	Description
max	int	1 to 99.

Returns CustomItem: This definition.

Model

public CustomItem Model(string modelId)

Sets the item model (minecraft:item_model).

Parameters

Name	Type	Description
modelId	string	The id of an item definition in the resource pack (assets/myplugin/items/ruby.json is "myplugin:ruby").

Returns CustomItem: This definition.

Name

public CustomItem Name(Component name)

Sets the display name (minecraft:item_name: not italic, replaced by an anvil rename).

Parameters

Name	Type	Description
name	Component	The name.

Returns CustomItem: This definition.

OnUse

public CustomItem OnUse(Action<ItemUseContext> handler)

Sets what happens when a player uses the item (right click in the air or on a block). Cancel the context to stop the vanilla behaviour of the base item.

Parameters

Name	Type	Description
handler	Action<ItemUseContext>	The handler.

Returns CustomItem: This definition.

OnUseOn

public CustomItem OnUseOn(Action<ItemUseContext> handler)

Sets what happens when a player uses the item on a block (after {{cref:M:Mc.Scripting.Content.CustomItem.OnUse(System.Action{Mc.Scripting.Content.ItemUseContext})}}).

Parameters

Name	Type	Description
handler	Action<ItemUseContext>	The handler.

Returns CustomItem: This definition.

Places

public CustomItem Places(CustomBlock block)

Makes the item place a custom block against the clicked face (and use up one item).

Parameters

Name	Type	Description
block	CustomBlock	The block (registered by the same plugin).

Returns CustomItem: This definition.

WithRarity

public CustomItem WithRarity(ItemRarity rarity)

Sets the rarity.

Parameters

Name	Type	Description
rarity	ItemRarity	The rarity.

Returns CustomItem: This definition.

See also

Component · CustomBlock · ItemRarity · ItemStack · ItemUseContext