ItemStack

Item stacks, stacked items, items in a stack (sometimes with data, too)

This page was created with KubeJS 7.2 (for 1.21.1) in mind. Most of the information you see here will work with your version as well, but code syntax especially might slightly differ across versions.
We are working on creating alternate versions of this page for other versions of Minecraft.
An ItemStack is an item associated with an amount and optionally some data attached to it. Or to put it slightly differently, it is... well, _a single stack_ of items that all share the same data. It is also the representation of an "item" that is most familiar to players, since item stacks are what you hold in your inventory, pick up from the ground, etc.
You may consider the Item contained in an ItemStack to basically just be the raw "definition" of what that item is; for example, all diamond axes share the same item ID minecraft:diamond_axe, they all use the same item, but two diamond axes with different amounts of damage in your inventory, like diamond_axe[damage=123] and diamond_axe[damage=456] would be part of different item stacks since their data doesn't overlap. Similarly, two sticks with custom lore stick[lore=[{text:"This Stick is very sticky."}]] would work as part of the same item stack.
Since 1.20.4, data on items has changed significantly with the transition from NBT to data components. A neat side effect of this is that you can now change and override things that used to be hardcoded into the item definition itself, like the item's max stack size, enchantibility, repair ingredients, etc.

#Creating ItemStacks

KubeJS will automatically try to wrap any input to an item stack in places where it is expected, but you can also use the Item wrapper (source) to explicitly create them yourself, specifically using Item.of(input) and Item.of(input, count):
In this case, the most simple way to write an item (and the one we recommend here) is by specifying its string ID, which you can most easily find by either enabling advanced tooltips in your game (press F3+H) and hovering over the item in your inventory, or by using the ever-useful /kubejs hand!
Here are some example string inputs that will parse to item stacks:
  • 'minecraft:air' is the empty item, which... doesn't seem particularly useful, but hey, maybe good to know still!
  • 'minecraft:apple' is a single apple. (Note: If you're using vanilla items, the minecraft: may be omitted as well!)
  • '2x minecraft:apple' represents a stack of two apples together.
  • '3x stick[lore=[{text:"This Stick is very sticky."}]]' represents a stack of three very sticky sticks (with custom data components!)
Also note that while possible in some older versions of KubeJS, Ingredients are unsupported and WILL now error if you try to convert them to an ItemStack implicitly, just use ingredient.first!

#Using ItemStacks

#Useful Methods and Properties

  • item.block: If this item is a BlockItem, returns the associated block, else null
  • item.count (writable): The count of this item stack
    • related: item.grow(amount) and item.shrink(amount) in- or decrease the current stack's count by amount
    • related: item.withCount(count): Copies this stack with the specified count
  • item.areItemsEqual(other): Returns true if item and other have the same item type
  • item.areComponentsEqual(other): Returns true if item and other have the same item and data

#Registry Object Functions

(these functions are all present on Item as well)
  • item.id: Returns the item's ID in the item registry (as a string)
    • related: item.idLocation (as ResourceLocation), item.key (as ResourceKey<Item>)
    • related: item.mod returns namespace the item was registered for
  • item.holder: Wraps this item as a Holder (internal registry object)
  • item.registry: Returns the item registry
    • related: item.registryId: Returns the key of the item registry
  • item.tags: Returns a list of all tags for this item
    • related: item.tagKeys: Returns a list of TagKey instead of ResourceLocation
    • related: item.hasTag(tag): Checks if this item has a certain tag

#Component Functions

WIP! (TODO: make a page on Components and KubeJS' ComponentFunctions interface)
  • componentString: Returns the item's data components as a string representation
  • withCustomName(name): Copies this item stack with the specified name
  • enchantments: Retrieves the item's enchantments
  • hasEnchantment(enchantment, level): Checks if the item has a specific enchantment at or above a given level
  • enchant(enchantment, level): Adds an enchantment to the ItemStack (TODO: enchantments page?)
  • enchant(enchantments): Adds enchantments to the ItemStack (TODO: enchantments page?)
  • getHarvestSpeed(block?): Gets the item's harvest speed for a given block (or default)
  • typeData: ??? (is this just a custom map for scripters to use to attach data to item definitions?)
  • toItemString(): Converts the ItemStack to its KubeJS string representation
  • asIngredient(): Converts the ItemStack to an Ingredient
  • withLore(lore): Copies this item stack with the specified lore text

#Further Reading