Player Inventory

Player Inventory

The inventory system manages player item storage including hotbar, main storage, armor, utility slots, and backpack.

Changed in Update 4

The inventory system was overhauled from a monolithic Inventory class to ECS-based InventoryComponent subclasses. Each inventory section (Hotbar, Storage, Armor, Utility, Backpack, Tool) is now a separate ECS component on the entity. The Inventory class still exists but is now a thin wrapper that delegates to the component system. LivingEntityInventoryChangeEvent was replaced by the ECS-based InventoryChangeEvent.

Package Location

com.hypixel.hytale.server.core.inventory

Overview

Player inventory is divided into sections, each with a unique section ID. Each section is a separate InventoryComponent subclass registered as an ECS component on the EntityStore. Active slots track which item the player currently has selected in each section.

Inventory Sections

Section ID	Constant	Capacity	Purpose
-1	HOTBAR_SECTION_ID	9	Main hotbar (0-8)
-2	STORAGE_SECTION_ID	36	Main storage (4x9 grid)
-3	ARMOR_SECTION_ID	6	Armor equipment
-5	UTILITY_SECTION_ID	4	Consumables (food, potions)
-8	TOOLS_SECTION_ID	23	Tools (deprecated)
-9	BACKPACK_SECTION_ID	Variable	Expandable storage

Core Classes

InventoryComponent (ECS)

Each inventory section is a separate InventoryComponent subclass registered as an ECS component:

package com.hypixel.hytale.server.core.inventory;

public abstract class InventoryComponent implements Component<EntityStore> {
    public ItemContainer getInventory();
    public void ensureCapacity(short capacity, List<ItemStack> remainder);
    public void markDirty();
    public boolean consumeIsDirty();
    public boolean consumeNeedsSaving();
}

Subclass	ComponentType accessor	Active slot
InventoryComponent.Hotbar	InventoryComponent.Hotbar.getComponentType()	getActiveSlot() / setActiveSlot(byte)
InventoryComponent.Storage	InventoryComponent.Storage.getComponentType()	—
InventoryComponent.Armor	InventoryComponent.Armor.getComponentType()	—
InventoryComponent.Utility	InventoryComponent.Utility.getComponentType()	getActiveSlot() / setActiveSlot(byte)
InventoryComponent.Backpack	InventoryComponent.Backpack.getComponentType()	—
InventoryComponent.Tool	InventoryComponent.Tool.getComponentType()	getActiveSlot() / setActiveSlot(byte)
InventoryComponent.Combined	InventoryComponent.Combined.getComponentType()	—

Combined Container Access

Use the static getCombined() method to build a CombinedItemContainer from multiple component types:

CombinedItemContainer combined = InventoryComponent.getCombined(
    accessor, ref, InventoryComponent.HOTBAR_FIRST
);

Predefined ordering arrays:

Array	Sections (in order)
HOTBAR_FIRST	Hotbar, Storage
STORAGE_FIRST	Storage, Hotbar
HOTBAR_STORAGE_BACKPACK	Hotbar, Storage, Backpack
BACKPACK_STORAGE_HOTBAR	Backpack, Storage, Hotbar
ARMOR_HOTBAR_UTILITY_STORAGE	Armor, Hotbar, Utility, Storage
EVERYTHING	Armor, Hotbar, Utility, Storage, Backpack

Getting the Item in Hand

ItemStack heldItem = InventoryComponent.getItemInHand(accessor, ref);

This checks the Tool component first, then falls back to the Hotbar component.

InventoryChangeEvent

InventoryChangeEvent is an ECS event fired when an inventory component changes. It replaces the former LivingEntityInventoryChangeEvent.

package com.hypixel.hytale.server.core.inventory;

public class InventoryChangeEvent extends EcsEvent {
    public ComponentType<EntityStore, ? extends InventoryComponent> getComponentType();
    public InventoryComponent getInventory();
    public ItemContainer getItemContainer();
    public Transaction getTransaction();
}

Inventory (Legacy Wrapper)

Deprecated in Update 4

The Inventory class is annotated @Deprecated(forRemoval = true) in v4. Use the ECS-based InventoryComponent subclasses instead. This wrapper may be removed in a future update.

The Inventory class still exists as a thin wrapper that delegates to the component system:

package com.hypixel.hytale.server.core.inventory;

@Deprecated(forRemoval = true)
public class Inventory {
    public static final int HOTBAR_SECTION_ID = -1;
    public static final int STORAGE_SECTION_ID = -2;
    public static final int ARMOR_SECTION_ID = -3;
    public static final int UTILITY_SECTION_ID = -5;
    public static final int TOOLS_SECTION_ID = -8;
    public static final int BACKPACK_SECTION_ID = -9;

    public ItemContainer getHotbar();
    public ItemContainer getStorage();
    public ItemContainer getArmor();
    public ItemContainer getUtility();
    public ItemContainer getTools();
    public ItemContainer getBackpack();
    public ItemContainer getSectionById(int sectionId);

    public byte getActiveHotbarSlot();
    public void setActiveHotbarSlot(
        Ref<EntityStore> ref, byte slot,
        ComponentAccessor<EntityStore> componentAccessor
    );
    public ItemStack getActiveHotbarItem();
    public ItemStack getItemInHand();

    public byte getActiveUtilitySlot();
    public void setActiveUtilitySlot(
        Ref<EntityStore> ref, byte slot,
        ComponentAccessor<EntityStore> componentAccessor
    );
    public ItemStack getUtilityItem();

    public void moveItem(
        int fromSectionId, int fromSlotId,
        int quantity,
        int toSectionId, int toSlotId
    );

    public void smartMoveItem(
        Ref<EntityStore> ref,
        int fromSectionId, int fromSlotId,
        int quantity,
        SmartMoveType moveType,
        PlayerSettings settings,
        ComponentAccessor<EntityStore> accessor
    );

    public List<ItemStack> dropAllItemStacks();
    public void clear();
}

Armor Slots

The armor section has 6 slots corresponding to ItemArmorSlot:

Slot Index	Position
0	Head
1	Chest
2	Legs
3	Feet
4	Cape
5	Accessory

Usage Examples

Accessing Inventory Components

import com.hypixel.hytale.server.core.inventory.InventoryComponent;
import com.hypixel.hytale.component.ComponentAccessor;
import com.hypixel.hytale.component.Ref;
import com.hypixel.hytale.server.core.universe.world.storage.EntityStore;
import com.hypixel.hytale.server.core.inventory.container.ItemContainer;

// access via ECS component system
Ref<EntityStore> ref = /* entity reference */;
ComponentAccessor<EntityStore> accessor = /* accessor */;

InventoryComponent.Hotbar hotbar = accessor.getComponent(
    ref, InventoryComponent.Hotbar.getComponentType()
);
InventoryComponent.Storage storage = accessor.getComponent(
    ref, InventoryComponent.Storage.getComponentType()
);
InventoryComponent.Armor armor = accessor.getComponent(
    ref, InventoryComponent.Armor.getComponentType()
);

// access underlying item container
if (hotbar != null) {
    ItemContainer hotbarContainer = hotbar.getInventory();
}

Working with Active Slots

// get currently held item (checks Tool then Hotbar component)
ItemStack heldItem = InventoryComponent.getItemInHand(accessor, ref);

// get active hotbar slot (0-8)
InventoryComponent.Hotbar hotbar = accessor.getComponent(
    ref, InventoryComponent.Hotbar.getComponentType()
);
if (hotbar != null) {
    byte activeSlot = hotbar.getActiveSlot();
    ItemStack activeItem = hotbar.getActiveItem();
    hotbar.setActiveSlot((byte) 3);
}

// utility items
InventoryComponent.Utility utility = accessor.getComponent(
    ref, InventoryComponent.Utility.getComponentType()
);
if (utility != null) {
    ItemStack utilityItem = utility.getActiveItem();
    utility.setActiveSlot((byte) 1);
}

Moving Items

// Move 1 item from hotbar slot 0 to storage slot 10
inventory.moveItem(
    Inventory.HOTBAR_SECTION_ID, 0,  // From
    1,                                // Quantity
    Inventory.STORAGE_SECTION_ID, 10  // To
);

// Move entire stack
ItemContainer hotbar = inventory.getHotbar();
ItemStack item = hotbar.getItemAt(0);
int quantity = item != null ? item.getQuantity() : 0;

inventory.moveItem(
    Inventory.HOTBAR_SECTION_ID, 0,
    quantity,
    Inventory.STORAGE_SECTION_ID, 10
);

Smart Move

import com.hypixel.hytale.protocol.SmartMoveType;
import com.hypixel.hytale.server.core.modules.entity.player.PlayerSettings;

// Auto-equip armor or merge stacks
inventory.smartMoveItem(
    ref,
    Inventory.STORAGE_SECTION_ID, 15,
    1,
    SmartMoveType.EquipOrMergeStack,
    playerSettings,
    accessor
);

// Move to hotbar or open window container
inventory.smartMoveItem(
    ref,
    Inventory.STORAGE_SECTION_ID, 20,
    1,
    SmartMoveType.PutInHotbarOrWindow,
    playerSettings,
    accessor
);

Bulk Operations

// Take all items from a container (e.g., chest)
var takeTransaction = inventory.takeAll(externalContainerId, playerSettings);

// Put all storage items into container
var putTransaction = inventory.putAll(externalContainerId);

// Quick stack matching items to container
var quickTransaction = inventory.quickStack(externalContainerId);

// Drop all items (on death)
List<ItemStack> droppedItems = inventory.dropAllItemStacks();

// Clear entire inventory
inventory.clear();

Combined Containers

import com.hypixel.hytale.server.core.inventory.InventoryComponent;
import com.hypixel.hytale.server.core.inventory.container.CombinedItemContainer;

// search hotbar first, then storage
CombinedItemContainer hotbarFirst = InventoryComponent.getCombined(
    accessor, ref, InventoryComponent.HOTBAR_FIRST
);

// search everything (armor, hotbar, utility, storage, backpack)
CombinedItemContainer everything = InventoryComponent.getCombined(
    accessor, ref, InventoryComponent.EVERYTHING
);

// iterate over combined container to find an item
for (short i = 0; i < everything.getCapacity(); i++) {
    ItemStack stack = everything.getItemStack(i);
    if (!ItemStack.isEmpty(stack) && stack.getItem().getId().equals("iron_sword")) {
        // found the item at slot i
        break;
    }
}

Working with Armor

// Get armor container
ItemContainer armor = inventory.getArmor();

// Get specific armor piece
ItemStack helmet = armor.getItemAt(0);  // Head
ItemStack chest = armor.getItemAt(1);   // Chest
ItemStack legs = armor.getItemAt(2);    // Legs
ItemStack feet = armor.getItemAt(3);    // Feet
ItemStack cape = armor.getItemAt(4);    // Cape
ItemStack accessory = armor.getItemAt(5); // Accessory

// Check if slot is empty
if (armor.isEmpty(0)) {
    // No helmet equipped
}

Checking Item in Hand

// get currently held item via the static helper
ItemStack heldItem = InventoryComponent.getItemInHand(accessor, ref);

if (heldItem != null) {
    Item item = heldItem.getItem();
    String itemId = item.getId();
    int quantity = heldItem.getQuantity();

    if (item.getWeapon() != null) {
        // holding a weapon
    } else if (item.getTool() != null) {
        // holding a tool
    } else if (item.getBlock() != null) {
        // holding a placeable block
    }
}

SmartMoveType

Options for intelligent item placement:

Value	Type	Description
0	EquipOrMergeStack	Try to equip as armor first, then merge with existing stacks across hotbar and storage
1	PutInHotbarOrWindow	Move to hotbar or open window container; swaps between hotbar and storage if already in one of those
2	PutInHotbarOrBackpack	Move to hotbar first, falls back to backpack/storage/hotbar combined

Slot Indices

• Hotbar: 0-8 (9 slots)
• Storage: 0-35 (36 slots, 4 rows x 9 columns)
• Armor: 0-5 (Head, Chest, Legs, Feet, Cape, Accessory)
• Utility: 0-3 (4 slots)
• Inactive indicator: -1 (no active slot)

Related

• Inventory System - Full inventory API
• Entity System - Player entity
• Item System - Item types and stacks