Creating an ItemStack


These docs were written for SpongeAPI 7 and are likely out of date. If you feel like you can help update them, please submit a PR!

If you want to create your own items, you need to go through several steps. Let’s go through a basic example and create an enchanted diamond sword.

To create an ItemStack, we need to first grab the builder from the ItemStack. This is done with the ItemStack#builder() method. In the builder, we can specify things such as the ItemType or the quantity of the item. In our example, we will be creating a diamond sword that contains enchantments, a custom name, and is unbreakable. If you want a plain sword without any other data, then this is all you need to do:

import org.spongepowered.api.item.ItemTypes;
import org.spongepowered.api.item.inventory.ItemStack;

public ItemStack generateSword() {
    ItemStack superMegaAwesomeSword = ItemStack.builder()
    return superMegaAwesomeSword;

Creating the basic item is done. Now this is a normal diamond sword that we created, but what if we wanted something more interesting? What about enchanting and naming our sword? We can use EnchantmentData to give our sword some enchantments. The following example will give our sword every enchantment in the game, to level 1000. Make sure to include this all before return superMegaAwesomeSword;.

import java.util.List;

import org.spongepowered.api.Sponge;
import org.spongepowered.api.item.Enchantment;

EnchantmentData enchantmentData = superMegaAwesomeSword
final List<EnchantmentType> enchantments = Sponge.getRegistry()

for (EnchantmentType enchantment : enchantments) {
        .add(Enchantment.of(enchantment, 1000)));

Now let’s say we wanted to give our overpowered sword a cool name to go with it. Here, we can directly offer a key to the ItemStack. Using this key, we can change the name of the ItemStack to “SUPER MEGA AWESOME Diamond Sword”

import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.TextComponent;
import net.kyori.adventure.text.format.NamedTextColor;
import org.spongepowered.api.item.ItemTypes;

superMegaAwesomeSword.offer(Keys.DISPLAY_NAME, TextComponent.ofChildren(
    Component.text("SUPER ", NamedTextColor.BLUE),
    Component.text("MEGA ", NamedTextColor.GOLD),
    Component.text("AWESOME ", NamedTextColor.DARK_AQUA),

Finally, to make the sword unbreakable, we can use keys again:

superMegaAwesomeSword.offer(Keys.UNBREAKABLE, true);

That’s it. You now have a fully enchanted, unbreakable, and beautifully named sword which you can give to players.

Spawning the Item

Sure, we can simply put the sword into a player’s inventory, but what if we wanted to throw it out into the open world and spawn the item? This is where entity spawning comes into play. Since the in-game graphical representation of an ItemStack is Item, we can spawn it in similarly to a normal Entity. The EntityType will simply be EntityTypes#ITEM and we will need to specify that the Entity will represent our ItemStack. This can be done using the Keys#REPRESENTED_ITEM key. An example is shown below:

import org.spongepowered.api.entity.Entity;
import org.spongepowered.api.entity.EntityTypes;
import org.spongepowered.api.event.CauseStackManager.StackFrame;

import java.util.Optional;

public void spawnItem(ItemStack superMegaAwesomeSword, Location<World> spawnLocation) {
    Extent extent = spawnLocation.getExtent();
    Entity item = extent.createEntity(EntityTypes.ITEM, spawnLocation.getPosition());
    item.offer(Keys.REPRESENTED_ITEM, superMegaAwesomeSword.createSnapshot());

    try (StackFrame frame = Sponge.getCauseStackManager().pushCauseFrame()) {
        frame.addContext(EventContextKeys.SPAWN_TYPE, SpawnTypes.PLACEMENT);

Creating an ItemStack From a Block

An ItemStack for a block can be created by using the method ItemStack.Builder#itemType(ItemType) similarly to normal items, but what if we wanted to create an ItemStack from a BlockState itself? To create an ItemStack from a BlockState, you would need to use the ItemStack.Builder#fromBlockState(BlockState) method on the ItemStack builder. An example of this is shown below:

import org.spongepowered.api.block.BlockState;

public ItemStack createStack(BlockState state) {
    return ItemStack.builder().fromBlockState(state).build();