Skip to content

These docs were made completely by AI, so they might be right, or wrong, you'll need to test them yourself. This was made for a easier understanding of everything. So use at your own risk. If anything is wrong, please don't hurt to make a PR on the page you have a problem with. ON GITHUB

Item System Overview

The item system in LCE is built around the Item base class. Every non-block item gets a numeric ID starting at 256 (the id you pass to the constructor gets +256 added internally). The global registry has room for up to 32,000 slots.

  • Tools & Weapons - Swords, pickaxes, axes, shovels, hoes, shears. Tool tiers, durability, speed, damage.
  • Armor - All armor materials, defense values, durability, slots, leather dyeing.
  • Food - Nutrition, saturation, effects, all food types.
  • Combat Items - Bow, arrows, snowballs, ender pearls, fire charges, potions.
  • Music Discs - All disc IDs, field names, how records work.
  • Decorative & Placement - Paintings, item frames, signs, buckets, dyes, maps, books, beds.
  • Raw Materials - Ingots, diamonds, redstone, glowstone dust, string, leather, and crafting ingredients.
  • Special Items - Spawn eggs, enchanted books, written books, fireworks, name tags.

Files: Minecraft.World/Item.h, Minecraft.World/Item.cpp

The Item class extends enable_shared_from_this<Item> so it can create shared_ptr references to itself when needed by the engine.

ConstantValuePurpose
ITEM_NUM_COUNT32000Maximum possible items in the registry
MAX_STACK_SIZE64Default max stack size (from Container::LARGE_MAX_STACK_SIZE)
ICON_COLUMNS16Columns in the item texture atlas
ICON_DESCRIPTION_PREFIX"item."Prefix for icon description lookup (static wstring)
VariableTypeAccessDefaultPurpose
idconst intpublic256 + constructor paramUnique item identifier, set once in the constructor
maxStackSizeintprotected64Maximum number per inventory slot
maxDamageintprivate0Maximum durability (0 means the item can’t be damaged)
iconIcon*protectedNULLTexture icon reference, set during registerIcons()
m_iBaseItemTypeintprotectedeBaseItemType_undefined (0)Crafting menu item type classification
m_iMaterialintprotectedeMaterial_undefined (0)Crafting menu material classification
m_handEquippedboolprotectedfalseWhether item renders held in hand like a tool
m_isStackedByDataboolprotectedfalseWhether aux data differentiates stack types (used by golden apples)
craftingRemainingItemItem*privateNULLItem left in crafting grid after use (e.g., empty bucket)
potionBrewingFormulawstringprivate"" (empty)Potion brewing modifier string
descriptionIdunsigned intprivate(uninitialized)Localized name string ID from string table
useDescriptionIdunsigned intprivate(uninitialized)Localized description string ID from string table
m_textureNamewstringprivate"" (empty)Texture resource name for atlas lookup
static ItemArray items; // size: ITEM_NUM_COUNT (32000)

Every Item constructor writes itself into this array at index 256 + id. Anything in the game that needs an item (inventory, crafting, drops) looks it up by index.

Item::Item(int id) : id(256 + id)
{
maxStackSize = Item::MAX_STACK_SIZE; // 64
maxDamage = 0;
icon = NULL;
m_handEquipped = false;
m_isStackedByData = false;
craftingRemainingItem = NULL;
potionBrewingFormula = L"";
m_iMaterial = eMaterial_undefined;
m_iBaseItemType = eBaseItemType_undefined;
m_textureName = L"";
if (items[256 + id] != NULL)
{
// "CONFLICT @ id" debug message
}
items[256 + id] = this;
}

The constructor takes the given ID, adds 256 to it, and registers the item into the global items array at that index. If the slot is already taken, a debug message gets printed. All defaults are set here, so subclasses only need to override what they change.

All setter methods return Item* (or a subclass pointer) so you can chain them together:

Item *setTextureName(const wstring &name); // Sets m_textureName for atlas lookup
Item *setMaxStackSize(int max); // Override default 64
Item *setBaseItemTypeAndMaterial(int iType, int iMaterial); // Crafting menu classification
Item *setMaxDamage(int maxDamage); // Set durability (protected, used by subclasses)
Item *setDescriptionId(unsigned int id); // Localized item name
Item *setUseDescriptionId(unsigned int id); // Localized item description
Item *setCraftingRemainingItem(Item *item); // Item left after crafting (e.g., bucket)
Item *setPotionBrewingFormula(const wstring &formula); // Brewing ingredient modifier (protected)
Item *setStackedByData(bool isStackedByData); // Aux-value-based stacking (protected)
Item *handEquipped(); // Sets m_handEquipped = true

These are every virtual method on the Item base class. Subclasses override the ones they need.

MethodReturnDefault BehaviorWhen Called
useOn(itemInstance, player, level, x, y, z, face, clickX, clickY, clickZ, bTestUseOnOnly)boolReturns falseRight-click on a block face. The bTestUseOnOnly param is true when the game is just checking for tooltip display, not actually doing the action.
use(itemInstance, level, player)shared_ptr<ItemInstance>Returns the item unchangedRight-click in air (not aiming at a block)
useTimeDepleted(itemInstance, level, player)shared_ptr<ItemInstance>Returns the item unchangedWhen the use duration timer runs out (eating, drinking)
getDestroySpeed(itemInstance, tile)floatReturns 1.0fMining speed multiplier against a specific tile
hurtEnemy(itemInstance, mob, attacker)boolReturns falseWhen hitting a mob. Return true if the item was used in combat.
mineBlock(itemInstance, level, tile, x, y, z, owner)boolReturns falseWhen a block is mined with this item. The tile param is the tile ID.
getAttackDamage(entity)intReturns 1Query base attack damage value
canDestroySpecial(tile)boolReturns falseWhether this tool can harvest a specific tile (e.g., iron pickaxe can harvest gold ore)
interactEnemy(itemInstance, mob)boolReturns falseWhen right-clicking a mob with this item
isHandEquipped()boolReturns m_handEquippedWhether to render the item as a hand-held tool
isMirroredArt()boolReturns falseWhether the item sprite should be horizontally mirrored (fishing rod uses this)
getUseAnimation(itemInstance)UseAnimReturns UseAnim_noneAnimation type when using the item
getUseDuration(itemInstance)intReturns 0How long the use action takes in ticks
releaseUsing(itemInstance, level, player, durationLeft)voidNo-opCalled when the use button is released early (bow charging)
isFoil(itemInstance)boolReturns true if itemInstance->isEnchanted()Whether the item has an enchantment glint
getRarity(itemInstance)const Rarity*Returns Rarity::rare if enchanted, otherwise Rarity::commonItem rarity (affects name color)
isEnchantable(itemInstance)boolReturns true if getMaxStackSize() == 1 && canBeDepleted()Whether item can go on the enchanting table
getEnchantmentValue()intReturns 0Enchantability score for the enchanting table RNG
isValidRepairItem(source, repairItem)boolReturns falseWhether the given item can repair this one in an anvil
isComplex()boolReturns falseWhether item needs special network sync (maps use this)
appendHoverText(itemInstance, player, lines, advanced, unformattedStrings)voidNo-opAdd extra lines to the item tooltip
getHoverName(itemInstance)wstringReturns app.GetString(getDescriptionId(itemInstance))Get the display name of the item
getColor(item, spriteLayer)intReturns 0xFFFFFF (white)Tint color for a sprite layer (leather armor uses this)
hasMultipleSpriteLayers()boolReturns falseWhether the item uses layered sprites (leather armor overlay)
getLayerIcon(auxValue, spriteLayer)Icon*Returns getIcon(auxValue)Get the icon for a specific sprite layer
inventoryTick(itemInstance, level, owner, slot, selected)voidNo-opCalled each tick while the item is in an inventory
onCraftedBy(itemInstance, level, player)voidNo-opCalled when the item is crafted by a player
registerIcons(iconRegister)voidRegisters m_textureName with the icon registerCalled during texture loading to register the item’s icon
shouldMoveCraftingResultToInventory(instance)boolReturns trueWhether the crafted result should auto-move to inventory (4J addition)
shouldOverrideMultiplayerNBT()boolReturns trueWhether NBT should be synced in multiplayer
TestUse(level, player)boolReturns falsePre-check before use() is called
getIconType()intReturns Icon::TYPE_ITEMWhether this is an item or tile icon
getIcon(auxValue)Icon*Returns iconGet the icon for a given aux value
getMaxStackSize()intReturns maxStackSizeMaximum stack size
getLevelDataForAuxValue(auxValue)intReturns 0Convert aux value to level data
getDescriptionId(iData)unsigned intReturns descriptionIdGet the string table ID, optionally for a specific data value
getDescriptionId(instance)unsigned intReturns descriptionIdGet the string table ID for an item instance
getUseDescriptionId()unsigned intReturns useDescriptionIdGet the use description string table ID
getUseDescriptionId(instance)unsigned intReturns useDescriptionIdGet the use description for a specific instance
getPotionBrewingFormula()wstringReturns potionBrewingFormulaGet the brewing formula string
hasPotionBrewingFormula()boolReturns !potionBrewingFormula.empty()Whether this item has a brewing formula
MethodReturnPurpose
getBaseItemType()intReturns m_iBaseItemType
getMaterial()intReturns m_iMaterial
getIcon(itemInstance)Icon*Calls getIcon(itemInstance->getAuxValue())
useOn(itemInstance, level, x, y, z, face, bTestUseOnOnly)const boolSimplified useOn without player/click params, always returns false
isStackedByData()boolReturns m_isStackedByData
getMaxDamage()intReturns maxDamage
canBeDepleted()boolReturns maxDamage > 0 && !m_isStackedByData
getDescription()LPCWSTRLooks up localized name from string table
getDescription(instance)LPCWSTRLooks up localized name for a specific instance
getCraftingRemainingItem()Item*Returns craftingRemainingItem
hasCraftingRemainingItem()boolReturns craftingRemainingItem != NULL
getName()wstringReturns empty string (not fully implemented)

File: Minecraft.World/UseAnim.h

enum UseAnim {
UseAnim_none, // No animation
UseAnim_eat, // Eating food
UseAnim_drink, // Drinking potions
UseAnim_block, // Blocking with sword
UseAnim_bow // Drawing a bow
};

File: Minecraft.World/Rarity.h

RarityUsage
commonMost items
uncommonEnchanted items, enchanted books (with stored enchantments)
rareEnchanted items (base class default), golden apples (aux 0), music discs
epicEnchanted golden apples (aux > 0)

Note: the base Item::getRarity() returns Rarity::rare when enchanted, while Rarity::common is the default. The uncommon rarity is used by EnchantedBookItem which overrides getRarity().

Files: Minecraft.World/ItemInstance.h, Minecraft.World/ItemInstance.cpp

ItemInstance represents a specific stack of items sitting in an inventory or out in the world. It wraps an Item with a count, auxiliary data, and NBT tag data. It also extends enable_shared_from_this<ItemInstance>.

ConstantTypeValuePurpose
TAG_ENCH_IDconst wchar_t*"id"NBT tag key for enchantment ID
TAG_ENCH_LEVELconst wchar_t*"lvl"NBT tag key for enchantment level
FieldTypeAccessPurpose
idintpublicItem ID (matches Item::id)
countintpublicStack count
popTimeintpublicPickup animation timer
tagCompoundTag*publicNBT data (enchantments, display name, repair cost, etc.)
auxValueintprivateAuxiliary/damage value. For tools, this tracks durability damage. For other items, it’s metadata.
m_bForceNumberDisplayboolprivateForces count display in the trading menu (4J addition)
frameshared_ptr<ItemFrame>privateReference to the item frame holding this item (TU9 addition)
ItemInstance(Tile *tile); // From a tile, count 1, aux 0
ItemInstance(Tile *tile, int count); // From a tile with count
ItemInstance(Tile *tile, int count, int auxValue); // From a tile with count and aux
ItemInstance(Item *item); // From an item, count 1, aux 0
ItemInstance(MapItem *item, int count); // From a map item (4J addition)
ItemInstance(Item *item, int count); // From an item with count
ItemInstance(Item *item, int count, int auxValue); // From an item with count and aux
ItemInstance(int id, int count, int damage); // From raw ID, count, and damage

All constructors call _init(id, count, auxValue) which sets popTime = 0, tag = NULL, frame = nullptr, and m_bForceNumberDisplay = false.

static shared_ptr<ItemInstance> fromTag(CompoundTag *itemTag);

Creates an ItemInstance from NBT data. Returns nullptr if the loaded item doesn’t exist in the registry.

MethodPurpose
getItem()Returns Item::items[id], the Item definition for this instance
remove(count)Splits off count items into a new instance, copies NBT tag. Clamps remaining count to 0.
copy()Creates a full deep copy including NBT tag
copy_not_shared()Same but returns raw pointer (used by recipe code)
save(compoundTag)Writes id (short), Count (byte), Damage (short), and tag to NBT
load(compoundTag)Reads back from NBT
hurt(i, owner)Applies durability damage. Checks Unbreaking enchantment. Skips damage in creative mode. Breaks the item if damage exceeds max.
enchant(enchantment, level)Adds an enchantment entry to the ench list tag
isEnchanted()Returns true if the ench tag exists
getEnchantmentTags()Returns the ListTag<CompoundTag> of enchantments
getHoverName()Returns custom display name from tag.display.Name, or falls back to Item::getHoverName()
setHoverName(name)Sets a custom name in tag.display.Name
hasCustomHoverName()Checks if tag.display.Name exists
getBaseRepairCost()Returns tag.RepairCost (int), or 0 if not set
setRepairCost(cost)Sets tag.RepairCost
isStackable()Returns `getMaxStackSize() > 1 && (!isDamageableItem()
isDamageableItem()Returns true if maxDamage > 0
isDamaged()Returns true if damageable and auxValue > 0
getDamageValue()Returns auxValue
getAuxValue()Returns auxValue
setAuxValue(value)Sets auxValue
sameItem(b)Checks if id and auxValue match (ignores count)
sameItemWithTags(b)Checks id, auxValue, and NBT tag equality
matches(a, b)Static method: full equality check including count and tags
tagMatches(a, b)Static method: checks only NBT tag equality
equals(ii)Checks id, count, and auxValue (no tag check)

The hurt() method is the core durability system:

  1. If the item isn’t damageable (maxDamage == 0), do nothing.
  2. If damage amount > 0 and the owner is a player, check the Unbreaking enchantment via EnchantmentHelper::getDigDurability(). On client side, always assume no damage (prevents desync). On server, roll a random check.
  3. Skip damage in creative mode (abilities.instabuild).
  4. Add i to auxValue.
  5. If auxValue > maxDamage, call owner->breakItem(), set count to 0, reset auxValue to 0.

When saved, an ItemInstance writes:

{
id: short // Item ID
Count: byte // Stack size
Damage: short // Aux/damage value
tag: { // Optional NBT
ench: [ // Enchantment list
{ id: short, lvl: short }
]
display: {
Name: string // Custom name
color: int // Leather armor color
}
RepairCost: int // Anvil repair cost
4jdata: int // 4J-specific data
}
}
MethodPurpose
set4JData(data)Stores a custom int in tag.4jdata
get4JData()Reads tag.4jdata, returns 0 if not set
hasPotionStrengthBar()Returns true for potions (id == potion and auxValue != 0)
GetPotionStrength()Decodes potion strength from aux value bitmask
ForceNumberDisplay(bForce)Forces count display in trading menu
GetForceNumberDisplay()Returns the force display flag
isFramed()Returns frame != NULL
setFramed(frame)Sets the item frame reference
getFrame()Returns the item frame reference

All items get registered in Item::staticCtor() inside Item.cpp. This method creates each item with new, sets properties through builder-pattern chaining, and the Item constructor automatically drops each item into the global Item::items array at index 256 + id.

// Example from staticCtor():
Item::sword_wood = (new WeaponItem(12, _Tier::WOOD))
->setBaseItemTypeAndMaterial(eBaseItemType_sword, eMaterial_wood)
->setTextureName(L"swordWood")
->setDescriptionId(IDS_ITEM_SWORD_WOOD)
->setUseDescriptionId(IDS_DESC_SWORD);

After staticCtor() runs, Item::staticInit() gets called separately (after other static constructors like Recipes) and builds item statistics through Stats::buildItemStats().

  1. Item::staticCtor() - creates all items, sets properties
  2. Recipes::staticCtor() - registers all crafting recipes (needs items to exist first)
  3. FurnaceRecipes::staticCtor() - registers smelting recipes
  4. Item::staticInit() - builds stats (must be after recipe constructors)
Item (base class, extends enable_shared_from_this<Item>)
|
+-- WeaponItem (swords)
+-- DiggerItem (base for mining tools)
| +-- PickaxeItem
| +-- ShovelItem
| +-- HatchetItem (axes)
+-- HoeItem
+-- ArmorItem
+-- FoodItem
| +-- BowlFoodItem (mushroom stew)
| +-- GoldenAppleItem
| +-- SeedFoodItem (carrots, potatoes)
+-- BowItem
+-- FishingRodItem
+-- ShearsItem
+-- BucketItem
+-- FlintAndSteelItem
+-- EnderpearlItem
+-- PotionItem
+-- BedItem
+-- DoorItem
+-- SignItem
+-- SeedItem
+-- TilePlanterItem (places a tile: cake, redstone repeater, etc.)
+-- TileItem (block-as-item wrapper)
+-- ComplexItem
| +-- MapItem
+-- RecordingItem (music discs)
+-- EnchantedBookItem
+-- MonsterPlacerItem (spawn eggs)
+-- BookItem
+-- BottleItem (glass bottles)
+-- CoalItem
+-- DyePowderItem
+-- RedStoneItem
+-- SaddleItem
+-- SnowballItem
+-- EggItem
+-- BoatItem
+-- MinecartItem
+-- CompassItem
+-- ClockItem
+-- EnderEyeItem
+-- ExperienceItem (bottle o' enchanting)
+-- FireChargeItem
+-- HangingEntityItem (paintings, item frames)
+-- SkullItem
+-- MilkBucketItem
+-- CarrotOnAStickItem

The crafting menu uses two enums to sort items for filtering. These were added by 4J Studios for the console edition’s crafting UI. Both are anonymous enums defined inside the Item class.

The crafting menu uses this to group items by material:

ValueNameExample Items
0undefinedGeneric items
1woodWood tools, sticks, doors
2stoneStone tools
3ironIron tools, iron armor, iron door
4goldGold tools, gold armor, gold nugget
5diamondDiamond tools, diamond armor
6clothLeather armor, painting
7chainChain armor
8detectorDetector rail
9lapisLapis lazuli
10musicMusic discs
11dyeDye powder
12sandSand-related
13brickBrick-related
14clayClay-related
15snowSnow-related
16bowBow
17arrowArrows
18compassCompass
19clockClock
20mapMap
21pumpkinPumpkin seeds
22glowstoneGlowstone
23waterBucket (water)
24trapTrapdoor
25flintandsteelFlint and Steel
26shearsShears
27pistonPiston
28stickypistonSticky Piston
29gateFence Gate
30stoneSmoothSmooth Stone
31netherbrickNether Brick
32enderEye of Ender
33glassGlass Bottle
34blazeBrewing Stand
35magicEnchanting-related
36melonMelon seeds, Speckled Melon
37setfireFire Charge
38sprucewoodSpruce wood stairs
39birchwoodBirch wood stairs
40junglewoodJungle wood stairs
41emeraldEmerald
42quartzNether Quartz
43appleGolden Apple
44carrotGolden Carrot, Carrot on a Stick

This groups items by what they actually do:

ValueNameExample Items
0undefinedGeneric items
1swordAll swords
2shovelAll shovels
3pickaxeAll pickaxes
4hatchetAll axes
5hoeAll hoes
6doorWood door, iron door
7helmetAll helmets
8chestplateAll chestplates
9leggingsAll leggings
10bootsAll boots
11ingot(Defined but unused; iron/gold ingots use treasure instead)
12railRails
13blockBlock items
14pressureplatePressure plates
15stairsStairs
16clothWool
17dyepowderDye powder
18structwoodstuffWood structure items
19structblockStructure blocks
20slabDouble slabs
21halfslabHalf slabs
22torchTorches, fire charges
23bowBow, arrows
24pockettoolCompass, clock, map, eye of ender
25utensilBuckets, bowl, cauldron, glass bottle
26pistonPistons
27devicetoolFlint and steel, shears
28fenceFences
29deviceBrewing stand
30treasureDiamond, iron/gold ingots, gold nugget, emerald
31seedSeeds
32HangingItemPainting, item frame, sign
33buttonButtons
34chestChests
35rodFishing rod, carrot on a stick
36giltFruitGolden apple, speckled melon
37carpetCarpets

The enum also has eBaseItemType_MAXTYPES as a sentinel value at the end.

MinecraftConsoles expands the item system pretty significantly. Here’s what changes:

ClassPurpose
FireworksItemFirework rockets. Has NBT tag constants for firework data (TAG_FIREWORKS, TAG_EXPLOSION, TAG_EXPLOSIONS, TAG_FLIGHT). Explosion types go from TYPE_SMALL (0) through TYPE_BURST (4). Places a FireworksRocketEntity on use.
FireworksChargeItemFirework stars. Multi-layer sprite with explosion tag reading for tooltip display.
NameTagItemName tags for naming mobs. Uses interactEnemy to apply the item’s custom name to a mob.
LeashItemLeads/leashes. useOn attaches leashed mobs to fences via bindPlayerMobs. Has a test method bindPlayerMobsTest for UI tooltip checks.
EmptyMapItemEmpty maps (separate from MapItem). Extends ComplexItem and creates a new map on use(). In LCEMP, map creation is handled within MapItem itself.
SpawnEggItemReplaces MonsterPlacerItem. Same spawn limit system but adds eSpawnResult_FailTooManyBats for the new bat mob. The class name change reflects the vanilla Minecraft naming.
SimpleFoiledItemA generic item that always shows the enchantment glint. Used for the Nether Star.
WrittenBookItemWritten (signed) books with title, author, and pages. Has validation for tag structure. In LCEMP, books don’t have the signed/written variant. Note: the implementation exists only as a commented-out Java pseudocode block in the header.

Some items got renamed between LCEMP and MinecraftConsoles:

LCEMP nameMinecraftConsoles name
monsterPlacerspawnEgg
sulphurgunpowder
milkbucket_milk
dioderepeater
netherStalkSeedsnetherwart_seeds
boots_cloth / helmet_cloth / etc.boots_leather / helmet_leather / etc.

These items exist in MinecraftConsoles but not LCEMP:

  • fireworks, fireworksCharge
  • nameTag, lead (leash)
  • netherStar
  • horseArmorMetal, horseArmorGold, horseArmorDiamond
  • minecart_hopper, minecart_tnt
  • comparator (separate from the diode/repeater)
  • emptyMap (separate from filled map)

The hierarchy gains SpawnEggItem (replacing MonsterPlacerItem), FireworksItem, FireworksChargeItem, NameTagItem, LeashItem, SimpleFoiledItem, EmptyMapItem, and WrittenBookItem.