Skip to content

Items Module

STBrian edited this page Nov 9, 2026 · 2 revisions

The Items submodule provides functions to query existing Minecraft items, create and register custom items, weapons, and tools, configure their textures and tool tiers, and place them in the creative inventory.

Events

Game.Items.OnRegisterItems Triggered when the game initializes and registers items
Game.Items.OnRegisterItemsTextures Triggered when item textures are being registered
Game.Items.OnRegisterCreativeItems Triggered when the creative menu items are being added

Types

MCItem Represents a registered Minecraft item definition
MCItemInstance Represents an instance of an item in inventories or recipes
MCToolTier Represents a tool material tier (durability, mining level, damage)

Constants

Game.Items.ToolTiers.WOOD Built-in wood tool tier
Game.Items.ToolTiers.STONE Built-in stone tool tier
Game.Items.ToolTiers.IRON Built-in iron tool tier
Game.Items.ToolTiers.GOLD Built-in gold tool tier
Game.Items.ToolTiers.DIAMOND Built-in diamond tool tier

Functions

Game.Items.findItemByName Finds an item definition by its text identifier
Game.Items.findItemByID Finds an item definition by its numeric ID
Game.Items.getItemInstance Creates an MCItemInstance with count and metadata
Game.Items.newToolTier Creates a new custom MCToolTier object
Game.Items.registerItem Registers a new custom base item
Game.Items.registerSwordItem Registers a new custom sword
Game.Items.registerPickaxeItem Registers a new custom pickaxe
Game.Items.registerAxeItem Registers a new custom axe
Game.Items.registerShovelItem Registers a new custom shovel
Game.Items.registerHoeItem Registers a new custom hoe
Game.Items.registerCreativeItem Adds a registered item to the creative inventory
Game.Items.getCreativePosition Gets an item's position in a creative category group

Game.Items.OnRegisterItems

Fires when the game is ready to register custom items. Custom items and tools should be registered within this event.

Game.Items.OnRegisterItems:Connect(function()
end)

Game.Items.OnRegisterItemsTextures

Fires when the game assigns textures to items. Use item:setTexture(name, index) inside this callback.

Game.Items.OnRegisterItemsTextures:Connect(function()
end)

Game.Items.OnRegisterCreativeItems

Fires when the creative inventory tabs are populated. Use Game.Items.registerCreativeItem inside this callback.

Game.Items.OnRegisterCreativeItems:Connect(function()
end)

Game.Items.findItemByName

Finds a registered Minecraft item by name (e.g. "diamond", "iron_ingot"). Returns the MCItem or nil if not found.

Game.Items.findItemByName(name: string) -> MCItem?

Example

local diamond = Game.Items.findItemByName("diamond")
if diamond then
    Core.Debug.message("Found diamond item ID: " .. tostring(diamond.ID))
end

Game.Items.findItemByID

Finds a registered Minecraft item by numeric ID (e.g. 264 for diamond). Returns MCItem?.

Game.Items.findItemByID(itemID: integer) -> MCItem?

Game.Items.getItemInstance

Creates a new MCItemInstance object from an MCItem definition with the specified count and data/durability value.

Game.Items.getItemInstance(item: MCItem, count: integer, data: integer) -> MCItemInstance

Game.Items.newToolTier

Allocates and returns a new empty MCToolTier object that you can configure and pass to tool registration functions.

Game.Items.newToolTier() -> MCToolTier

Example

local obsidianTier = Game.Items.newToolTier()
obsidianTier.MiningLevel = 4
obsidianTier.Durability = 2500
obsidianTier.MiningEfficiency = 10.0
obsidianTier.DamageBonus = 4.0
obsidianTier.Enchantability = 15

Game.Items.registerItem

Registers a new basic item. Can be called with 2 arguments (itemName, itemId) or 3 arguments (namespace, itemName, itemId).

Game.Items.registerItem(namespace: string, itemName: string, itemId: integer) -> MCItem?

Game.Items.registerSwordItem

Registers a new sword weapon with the given MCToolTier.

Game.Items.registerSwordItem(itemName: string, itemId: integer, tier: MCToolTier) -> MCItem?

Game.Items.registerPickaxeItem

Registers a new pickaxe tool with the given MCToolTier.

Game.Items.registerPickaxeItem(itemName: string, itemId: integer, tier: MCToolTier) -> MCItem?

Game.Items.registerAxeItem

Registers a new axe tool with the given MCToolTier.

Game.Items.registerAxeItem(itemName: string, itemId: integer, tier: MCToolTier) -> MCItem?

Game.Items.registerShovelItem

Registers a new shovel tool with the given MCToolTier.

Game.Items.registerShovelItem(itemName: string, itemId: integer, tier: MCToolTier) -> MCItem?

Game.Items.registerHoeItem

Registers a new hoe tool with the given MCToolTier.

Game.Items.registerHoeItem(itemName: string, itemId: integer, tier: MCToolTier) -> MCItem?

Game.Items.registerCreativeItem

Appends a registered MCItem to a creative menu category group at the specified position.

Game.Items.registerCreativeItem(item: MCItem, groupId: integer, position: integer)

Game.Items.getCreativePosition

Returns the position index of an item in the creative menu for a given category group.

Game.Items.getCreativePosition(itemID: integer, groupID: integer) -> number

Clone this wiki locally