Hytale Inventory

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.component.Store;
import com.hypixel.hytale.protocol.packets.interface_.Page;
import com.hypixel.hytale.server.core.inventory.Inventory;
import com.hypixel.hytale.server.core.inventory.ItemStack;
import com.hypixel.hytale.server.core.inventory.container.ItemContainer;
import com.hypixel.hytale.server.core.universe.world.storage.EntityStore;
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 the player's page manager and the Page enum to open inventory UI screens.

Available Pages

Opening a Page

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

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

Closing a Page

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

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

Container-Backed Items

The updated inventory docs now cover custom inventories stored inside items themselves.

Item JSON Setup

Add a container to the item definition:

"Container": {
    "Capacity": 9
}

Open that container with a built-in interaction:

"Interactions": {
    "Use": {
        "Interactions": [
            {
                "Type": "OpenItemStackContainer"
            }
        ]
    }
}

Editing Container Items from a Plugin

Container contents are stored in the held item's BSON metadata, not as ECS-backed child entities.

• Read the held item and its active hotbar slot.
• Decode the container data from the item's metadata.
• Modify a local copy of the contained ItemStack[] data.
• Write the updated metadata to a new ItemStack with withMetadata(...).
• Replace the original slot with setItemStackForSlot(...) because ItemStack values are immutable.

When to Use This Pattern

• Use normal Inventory and ItemContainer APIs for player inventory sections like hotbar, storage, armor, and backpack.
• Use container-backed item metadata when the item itself owns its own internal storage, such as bags, boxes, or utility items with embedded contents.

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