Inventory Management

In this guide, you'll learn how to manage player inventories in your Hytale mod.

Accessing the Player Inventory

To access the Inventory of a Player, you can use the getInventory() method which returns the Inventory object.

Inventory inventory = player.getInventory();

Opening Inventories

You can open different types of inventories, these inventories are known as "Pages". You can also add custom pages, this will be covered in a guide later on.

You can use the Page enum to reference existing inventories, currently the following pages are available:

Page.None
Page.Bench
Page.Inventory
Page.ToolsSettings
Page.Map
Page.MachinimaEditor
Page.ContentCreation
Page.Custom

PageManager pageManager = player.getPageManager();
Store<EntityStore> store = player.getWorld().getEntityStore().getStore();
pageManager.setPage(player.getReference(), store, Page.Inventory);

You can create and manipulate items in a player's inventory using the ItemStack class. This class represents a stack of items, and provides methods for managing the quantity and type of items in the stack.

Creating an ItemStack

To create an ItemStack, you need to specify the material type and the quantity of items in the stack.

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

Adding custom metadata

You can also add custom metadata to a ItemStack by passing a BsonDocument when creating it.

BsonDocument metadata = new BsonDocument();
metadata.append("customData", new BsonString("value"));
ItemStack item = new ItemStack("Stone", 64, metadata);

Setting a durability

ItemStack stackWithDurability = new ItemStack(
    "DiamondSword", // itemId
    1,              // quantity
    100.0,          // durability
    100.0,          // maxDurability
    metadata        // metadata (optional)
);

Getting the `ItemContainer`

The Inventory class provides methods to get multiple ItemContainer objects, like:

.getStorage()
.getArmor()
.getBackpack()
.getHotbar()
.getUtility()

There are also combined methods like:

.getCombinedEverything()
.getCombinedArmorHotbarStorage()
.getCombinedBackpackStorageHotbar()
.getCombinedHotbarFirst()
.getCombinedStorageFirst()
.getCombinedArmorHotbarUtilityStorage()
.getCombinedHotbarUtilityConsumableStorage()

Adding `ItemStack` objects to the Inventory

To add an ItemStack to a player's inventory, you can use the addItemStack() method of the ItemContainer class.

Inventory inventory = player.getInventory();
ItemContainer storageContainer = inventory.getStorage();
storageContainer.addItemStack(item);

Or you can specify a certain slot to add it to:

storageContainer.addItemStackToSlot((short) 4, stack)

Removing `ItemStack` objects from the Inventory

To remove an ItemStack from a player's inventory, you can use the removeItemStack() method of the Inventory class.

Inventory inventory = player.getInventory();
ItemContainer storageContainer = inventory.getStorage();
storageContainer.removeItemStack(item);

Or you can specify a certain slot to remove it from:

storageContainer.removeItemStackFromSlot((short) 4);

Custom Inventories (Item Containers)

Adding an inventory to an item

You can add a custom inventory by adding the following to the items json

"Container": {
    "Capacity": 9
},

And adding the following interaction allows opening the inventory UI Page by using a pre defined UI page. It opens the UI like how it would for a backpackpack. This allows the player to see their inventory along with the items.

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

Plugin Interaction of Container Items

The items stored in an inventory are saved in the item BSON. Because of this they can not be access data through ECS when wanting to edit items. You will instead need to load the data from the BSON to interact with it and save it back to the BSON.

// Get held item that we know has a container field & its position in invenotory (Assume item its held for example)
ItemStack heldItemStack = player.getInventory().getActiveHotbarItem();
final short ACTIVE_HOTBAR_SLOT = player.getInventory().getActiveHotbarSlot();

// Get the container BSON of the item
BsonDocument containerBSON = heldItemStack.getFromMetadataOrNull(ItemStackItemContainer.CONTAINER_CODEC);

// Get the array of items in the container BSON
ItemStack[] containerItems = ItemStackItemContainer.ITEMS_CODEC.getOrNull(containerBSON, new ExtraInfo());

You can then modify the list of items however you want but this will not modify the item directly as item stacks on the player are immutable. To update the container the player is holding you will need to edit the item locally, then replace the held item with the newly made local copy. The following shows how to do that.

// For this example we are just removing the first item in the locally saved container (Continued from above)
containerItems[0] = null;

// Update the container fields in the BSON doc to have the removed item
ItemStackItemContainer.ITEMS_CODEC.put(containerBSON, containerItems, new ExtraInfo());

// Create a new version of the item
ItemStack updatedItem = heldItemStack.withMetadata(ItemStackItemContainer.CONTAINER_CODEC, containerBSON);

// Replace the equiped item in the players inventory with the new item as its not editable!
// - remove original item
player.getInventory().getHotbar().removeItemStackFromSlot(ACTIVE_HOTBAR_SLOT);
// - add new item
player.getInventory().getHotbar().setItemStackForSlot(ACTIVE_HOTBAR_SLOT, updatedItem);

Getting Components from Container Items

You can use a similar method to get any component from an item in a container

// Get the component data
CustomComponent customComponent = itemStack.getFromMetadataOrDefault(CustomComponent.CUSTOM_COMPONENT_ID, CustomComponent.CODEC);

// Modify component data here
customComponent.setSomeValue();

// Set the component data by creating new item with updated info
ItemStack newItem = itemStack.withMetadata(
        CustomComponent.CUSTOM_COMPONENT_ID,
        CustomComponent.CODEC,
        customComponent
    );

// Add updated item to the player
player.getInventory().getHotbar().setItemStackForSlot(0, newItem);