Hytale Inventory Management

Use this skill when managing player inventories, creating items, opening inventory pages, or manipulating item containers in Hytale plugins.

Related skills: For persistent player data, see hytale-persistent-data. For notifications with item icons, see hytale-notifications. For hotbar key actions, see hytale-hotbar-actions. For inventory change events, see hytale-events.

Quick Reference

Required Imports

import com.hypixel.hytale.server.item.ItemStack;
import com.hypixel.hytale.server.item.ItemContainer;
import com.hypixel.hytale.server.core.entity.entities.player.Inventory;
import com.hypixel.hytale.server.core.entity.entities.player.pages.Page;
import com.hypixel.hytale.server.core.entity.entities.player.pages.PageManager;
import com.hypixel.hytale.server.ecs.entity.EntityStore;
import com.hypixel.hytale.server.ecs.Store;
import org.bson.BsonDocument;
import org.bson.BsonString;

Accessing the Player Inventory

Get the Inventory object from a Player instance:

Inventory inventory = player.getInventory();

ItemStack

ItemStack represents a stack of items with a material type, quantity, optional metadata, and optional durability.

Creating an ItemStack

// Basic item (quantity defaults to 1)
ItemStack item = new ItemStack("Stone");

// Item with quantity
ItemStack stack = new ItemStack("Stone", 64);

ItemStack with Custom Metadata

Attach arbitrary BSON metadata to items:

BsonDocument metadata = new BsonDocument();
metadata.append("customData", new BsonString("value"));

ItemStack item = new ItemStack("Stone", 64, metadata);

ItemStack with Durability

Create items that have durability (e.g., tools, weapons):

ItemStack sword = new ItemStack(
    "DiamondSword",  // itemId
    1,               // quantity
    100.0,           // durability
    100.0,           // maxDurability
    metadata         // metadata (optional, can be null)
);

ItemContainer

ItemContainer represents a specific section of inventory (storage, hotbar, armor, etc.). All add/remove operations are performed on an ItemContainer.

Getting an ItemContainer

The Inventory class provides methods to get individual containers:

Combined Containers

For operations that span multiple containers, use combined methods:

Adding Items

Add to First Available Slot

Inventory inventory = player.getInventory();
ItemContainer storage = inventory.getStorage();

ItemStack item = new ItemStack("Stone", 64);
storage.addItemStack(item);

Add to Specific Slot

ItemContainer storage = inventory.getStorage();
ItemStack item = new ItemStack("Stone", 32);

storage.addItemStackToSlot((short) 4, item);

Removing Items

Remove by ItemStack

Inventory inventory = player.getInventory();
ItemContainer storage = inventory.getStorage();

storage.removeItemStack(item);

Remove from Specific Slot

ItemContainer storage = inventory.getStorage();
storage.removeItemStackFromSlot((short) 4);

Opening Inventory Pages

Use PageManager and the Page enum to open inventory UI screens for a player.

Available Pages

Opening a Page

PageManager pageManager = player.getPageManager();
Store<EntityStore> store = player.getWorld().getEntityStore().getStore();

pageManager.setPage(player.getReference(), store, Page.Inventory);

Closing a Page

PageManager pageManager = player.getPageManager();
Store<EntityStore> store = player.getWorld().getEntityStore().getStore();

pageManager.setPage(player.getReference(), store, Page.None);

Common Patterns

Give Items on Event

public void onPlayerReady(PlayerReadyEvent event) {
    var player = event.getPlayer();
    Inventory inventory = player.getInventory();
    ItemContainer hotbar = inventory.getHotbar();

    hotbar.addItemStackToSlot((short) 0, new ItemStack("Weapon_Sword_Iron", 1));
    hotbar.addItemStackToSlot((short) 1, new ItemStack("Tool_Pickaxe_Iron", 1));
    hotbar.addItemStackToSlot((short) 2, new ItemStack("Food_Apple", 16));
}

Clear Inventory

public void clearPlayerInventory(Player player) {
    Inventory inventory = player.getInventory();
    ItemContainer storage = inventory.getStorage();
    ItemContainer hotbar = inventory.getHotbar();
    ItemContainer armor = inventory.getArmor();

    // Remove items from each slot
    for (short i = 0; i < storage.getSize(); i++) {
        storage.removeItemStackFromSlot(i);
    }
    for (short i = 0; i < hotbar.getSize(); i++) {
        hotbar.removeItemStackFromSlot(i);
    }
    for (short i = 0; i < armor.getSize(); i++) {
        armor.removeItemStackFromSlot(i);
    }
}

Give Item with Metadata

public void giveCustomItem(Player player, String itemId, String customTag, String value) {
    BsonDocument metadata = new BsonDocument();
    metadata.append(customTag, new BsonString(value));

    ItemStack item = new ItemStack(itemId, 1, metadata);
    player.getInventory().getStorage().addItemStack(item);
}

Give Durable Tool

public void giveTool(Player player, String toolId, double maxDurability) {
    ItemStack tool = new ItemStack(
        toolId,
        1,
        maxDurability,
        maxDurability,
        null
    );
    player.getInventory().getHotbar().addItemStack(tool);
}

Related Events

Best Practices

1. Use the correct container — Add items to the appropriate container (hotbar for tools, armor for equipment, storage for general items).
2. Use combined containers for searches — When checking if a player has an item, use getCombinedEverything() or the appropriate combined method.
3. Cast slot indices to short — Slot methods require (short) cast for the index parameter.
4. Null-check metadata — The metadata BsonDocument parameter is optional and can be null.
5. Use Page.None to close — Always close pages with Page.None when done.
6. Localize item names — Use translation keys for any user-facing item text.

References

• Inventory Management Guide
• Hotbar Actions Skill — Custom hotbar key handling
• Notifications Skill — Item icons in notifications
• UI Modding Skill — Custom pages and UI