Player Inventory

Inventory Structure

Player inventory is divided into sections, each backed by an ItemContainer:

Section	Method	Slots	Section ID
Storage	`getStorage()`	36	`-2`
Hotbar	`getHotbar()`	9	`-1`
Armor	`getArmor()`	4	`-3`
Utility	`getUtility()`	4	`-5`
Tools	`getTools()`	23	`-8`
Backpack	`getBackpack()`	varies	`-9`

Accessing Inventory

Player player = store.getComponent(ref, Player.getComponentType());
Inventory inventory = player.getInventory();

// get specific sections
ItemContainer storage = inventory.getStorage();
ItemContainer hotbar = inventory.getHotbar();
ItemContainer armor = inventory.getArmor();
ItemContainer utility = inventory.getUtility();

ItemContainer Operations

Each section is an ItemContainer with these methods:

// get item at slot
ItemStack item = container.getItemStack(slot);

// set item at slot
container.setItemStackForSlot(slot, itemStack);

// add item (finds available space)
ItemStackTransaction tx = container.addItemStack(itemStack);

// add to specific slot
container.addItemStackToSlot(slot, itemStack);

// check if item can be added
boolean canAdd = container.canAddItemStack(itemStack);

// remove item from slot
container.removeItemStackFromSlot(slot);
container.removeItemStackFromSlot(slot, quantity);

// remove matching item
container.removeItemStack(itemStack);

// check if empty
boolean empty = container.isEmpty();

// get capacity
int slots = container.getCapacity();

// iterate items
container.forEach((slot, item) -> {
    // process each item
});

Active Slot Selection

// get/set selected hotbar slot (0-8)
byte selectedSlot = inventory.getActiveHotbarSlot();
inventory.setActiveHotbarSlot((byte) 0);

// get/set selected utility slot
byte utilitySlot = inventory.getActiveUtilitySlot();
inventory.setActiveUtilitySlot((byte) 0);

// get item in selected hotbar slot
ItemStack hotbarItem = inventory.getActiveHotbarItem();

// get item being used (considers tool slots)
ItemStack inHand = inventory.getItemInHand();

// get selected utility item
ItemStack utilityItem = inventory.getUtilityItem();

Combined Containers

For operations that search across multiple sections:

// searches hotbar first, then storage
ItemContainer combined = inventory.getCombinedHotbarFirst();

// searches storage first, then hotbar
ItemContainer combined = inventory.getCombinedStorageFirst();

// all sections combined
ItemContainer combined = inventory.getCombinedEverything();

Bulk Operations

// clear all sections
inventory.clear();

// remove and return all items
List<ItemStack> dropped = inventory.dropAllItemStacks();

// sort storage
inventory.sortStorage(SortType.NAME);  // also: TYPE, RARITY

Moving Items Between Sections

// move item between sections
inventory.moveItem(fromSectionId, fromSlot, quantity, toSectionId, toSlot);

Use the section ID constants from the Inventory Structure table (e.g. Inventory.HOTBAR_SECTION_ID for -1).

Syncing to Client

After modifying inventory server-side:

player.sendInventory();

ItemStack

Class: com.hypixel.hytale.server.core.inventory.ItemStack

ItemStack represents an item with a quantity, durability, and optional metadata. ItemStacks are immutable-style — modifier methods return a new instance.

Creating ItemStacks

// basic
ItemStack sword = new ItemStack("hytale:iron_sword");

// with quantity
ItemStack stones = new ItemStack("hytale:stone", 64);

// with metadata
BsonDocument meta = new BsonDocument();
ItemStack custom = new ItemStack("hytale:stone", 64, meta);

// full control
ItemStack full = new ItemStack("hytale:iron_sword", 1, 100.0, 100.0, meta);

ItemStack.EMPTY is the singleton empty item (itemId = "Empty").

Reading Properties

Method	Return Type	Description
`getItemId()`	`String`	Asset ID (e.g. `"hytale:stone"`)
`getQuantity()`	`int`	Stack count
`getDurability()`	`double`	Current durability
`getMaxDurability()`	`double`	Maximum durability
`isUnbreakable()`	`boolean`	True if `maxDurability <= 0`
`isBroken()`	`boolean`	True if `durability == 0` and not unbreakable
`isEmpty()`	`boolean`	True if this is the empty item
`getItem()`	`Item`	Resolves the `Item` asset config from the registry
`getBlockKey()`	`String`	Block type ID if this item places a block
`getMetadata()`	`BsonDocument`	Clone of metadata (prefer typed accessors below)

Modifying ItemStacks

All with*() methods return a new ItemStack:

// change quantity (returns null if quantity is 0)
ItemStack half = stones.withQuantity(32);

// change durability
ItemStack damaged = sword.withDurability(50.0);

// change item variant
ItemStack variant = item.withState("activated");

// set typed metadata
ItemStack tagged = item.withMetadata("MyKey", Codec.STRING, "myValue");

// set raw metadata
ItemStack raw = item.withMetadata("MyKey", new BsonString("myValue"));

Reading Metadata

Metadata is stored as a BsonDocument. Use typed accessors:

// read typed metadata (returns null if missing)
String value = itemStack.getFromMetadataOrNull("MyKey", Codec.STRING);

// read with default
MyData data = itemStack.getFromMetadataOrDefault("MyKey", MyData.CODEC);

Comparing ItemStacks

Method	What it compares
`isStackableWith(other)`	Same ID, durability, maxDurability, and metadata
`isEquivalentType(other)`	Same ID and metadata (ignores durability)
`ItemStack.isSameItemType(a, b)`	Same ID only (null-safe static)

Giving Items to a Player

Inventory inventory = player.getInventory();
ItemStack item = new ItemStack("hytale:iron_sword");

// add to first available slot (hotbar first, then storage)
ItemStackTransaction tx = inventory.getCombinedHotbarFirst().addItemStack(item);

// check for overflow
ItemStack remainder = tx.getRemainder();
if (remainder != null && !remainder.isEmpty()) {
    // drop overflow on ground
    ItemUtils.dropItem(ref, remainder, store);
}

Item Asset Config

itemStack.getItem() resolves to the Item asset config, which defines static properties:

Method	Description
`getMaxStack()`	Maximum stack size
`getMaxDurability()`	Default max durability
`getBlockId()`	Block this item places (if any)
`getWeapon()`	Weapon config
`getArmor()`	Armor config
`getTool()`	Tool config

Inventory Events

Inventory changes fire after-the-fact notification events — they cannot be cancelled.

LivingEntityInventoryChangeEvent fires whenever items are added, removed, or moved in any section. It provides the ItemContainer that changed and a Transaction describing the change. Keyed by world name.

eventRegistry.register(LivingEntityInventoryChangeEvent.class, event -> {
    ItemContainer container = event.getItemContainer();
    Transaction transaction = event.getTransaction();
    // react to inventory change
});

For cancellable item actions, use ECS events:

Event	When	Cancellable
DropItemEvent.PlayerRequest	Player requests to drop from a slot	Yes
DropItemEvent.Drop	Item about to be thrown into world	Yes
SwitchActiveSlotEvent	Hotbar slot selection changes	Yes
InteractivelyPickupItemEvent	Player picks up item from ground	Yes