# Components > A guide for using components in Minecraft with Kore. Updated 2026-10-23. Canonical: https://kore.ayfri.com/docs/concepts/components In Minecraft, data components are structured key-value properties used to define and store behavior and attributes. They are attached to different things: - Item components: properties that live on item stacks (e.g., `enchantments`, `food`, `attribute_modifiers`). They affect how items behave in inventories, commands, containers, etc. - Entity variant components: properties exposed as components for certain entity variants when represented as items or spawn eggs (e.g., `wolf/variant`, `cat/collar`). These follow the same component mechanics but target entity-specific customization. This page focuses on using item components with Kore. For the vanilla reference and exhaustive definitions, see the [Minecraft Wiki - Data component format](https://minecraft.wiki/w/Data_component_format). The [custom item example](https://kore.ayfri.com/playground#example=custom-item) of the playground builds an item with components and runs in your browser. The Kore library provides a comprehensive and user-friendly way to work with these components, enabling you to create custom items with ease. This article will guide you through the process of using components with Kore, showcasing examples and best practices. ## Creating Custom Items with Components Let's dive into creating custom items with various components using Kore. Below are examples of how to define and manipulate item properties such as attribute modifiers, enchantments, and more. ### Attribute Modifiers Attribute modifiers allow you to alter the attributes of an item, such as increasing damage or changing the scale. Here's how to define a stone sword with an attribute modifier using Kore: ```kotlin import io.github.ayfri.kore.commands.AttributeModifierOperation import io.github.ayfri.kore.generated.Items import io.github.ayfri.kore.generated.Attributes val attributeModifiersTest = Items.STONE_SWORD { attributeModifiers { modifier( type = Attributes.SCALE, amount = 1.0, name = "big", operation = AttributeModifierOperation.ADD_VALUE, ) } } ``` ### Enchantments You can add enchantments to items to give them special abilities. Here’s an example of adding the Sharpness enchantment to a stone sword: ```kotlin import io.github.ayfri.kore.generated.Enchantments val enchantmentsTest = Items.STONE_SWORD { enchantments(mapOf(Enchantments.SHARPNESS to 5)) } ``` Check out the [Enchantments](https://kore.ayfri.com/docs/data-driven/enchantments.md) article for more information on how to use enchantments with Kore. ### Custom Names and Lore Custom names and lore can be added to items to give them unique identifiers and background stories: ```kotlin import io.github.ayfri.kore.arguments.chatcomponents.textComponent import io.github.ayfri.kore.arguments.colors.Color val customNameTest = Items.STONE_SWORD { customName(textComponent("Legendary Sword", Color.AQUA)) } ``` ### Fireworks You can define the properties of fireworks, including the shape and colors of the explosions: ```kotlin import io.github.ayfri.kore.arguments.components.item.FireworkExplosionShape import io.github.ayfri.kore.arguments.colors.Color val fireworksTest = Items.FIREWORK_ROCKET { fireworks(flightDuration = 1) { explosion(FireworkExplosionShape.BURST) { colors(Color.AQUA) fadeColors(Color.BLACK, Color.WHITE) hasTrail = true hasTwinkle = true } } } ``` See how to set custom colors in the [Colors](https://kore.ayfri.com/docs/concepts/colors.md) article. ### Custom Block Data You can define custom properties for blocks using block entity data. Here's an example of adding custom data to a bee nest block: ```kotlin import io.github.ayfri.kore.generated.Blocks import io.github.ayfri.kore.generated.Items val blockEntityDataTest = Items.BEE_NEST { blockEntityData(Blocks.BEE_NEST) { this["test"] = "test" } } ``` ### Block Transformer `blockTransformer` turns the block the item is used on into another one, like axes stripping logs or honeycombs waxing copper. It takes the ID of a [block transformer file](https://kore.ayfri.com/docs/data-driven/block-transformers.md), either a vanilla one (`axe`, `hoe`, `shovel`) or one of your own. Inline rule lists aren't possible because the game only reads this component from a file. ```kotlin val strip = blockTransformer("strip_oak") { rule(ruleBasedStateProvider { rule(copyPropertiesProvider(simpleStateProvider(Blocks.STRIPPED_OAK_LOG, mapOf("axis" to "y")))) { matchingBlocks(Blocks.OAK_LOG) } }) { sound = SoundEvents.Item.Axe.STRIP } } val axe = Items.IRON_AXE { blockTransformer(strip) } val vanillaAxe = Items.IRON_AXE { blockTransformer(BlockTransformers.AXE) } ``` The rules, their options (`sound`, `loot`, `itemDamagePerUse`, ...) and their defaults are described on the [Block Transformers](https://kore.ayfri.com/docs/data-driven/block-transformers.md) page. ### Compostable `compostable` makes an item usable in a composter. It takes the number of layers added as an `Int` or as the ID of a [context int provider file](https://kore.ayfri.com/docs/data-driven/loot-tables.md#context-provider-files), either a vanilla one from `ContextIntProviders.Compostable` or one of your own. An inline provider object isn't possible because the game only reads a number or an ID there. ```kotlin val seeds = Items.WHEAT_SEEDS { compostable(ContextIntProviders.Compostable.LOW) } val pumpkin = Items.PUMPKIN { compostable(1) // compostable={layers:1} } val layers = contextIntProvider("my_layers", 1) val sapling = Items.OAK_SAPLING { compostable(layers) } ``` ### Cooking and brewing fuel `cookingFuel` makes an item burn in furnaces, smokers and blast furnaces, `brewingFuel` makes it power a brewing stand. Their fields are a plain number or the ID of a context provider file, never an inline provider object: the whole-number fields (`burnTime`, `uses`) take an `Int` or a [context int provider](https://kore.ayfri.com/docs/data-driven/loot-tables.md#context-provider-files) ID from `ContextIntProviders.Cooking` / `ContextIntProviders.Brewing` or your own, the speeds take a `Float` or a context float provider ID from `ContextFloatProviders.Cooking` / `ContextFloatProviders.Brewing` or your own. `cookingFuel` takes the burn time in ticks and a cooking speed (vanilla `ContextFloatProviders.Cooking.SPEED_DEFAULT` when omitted), `brewingFuel` takes both a speed and the number of brews, which have no default. `resolvableInt(...)` and `resolvableFloat(...)` wrap either form, to mix numbers and IDs in one component. There is no `#brewing_fuel` item tag: an item is a brewing fuel through this component. ```kotlin val stick = Items.STICK { cookingFuel(ContextIntProviders.Cooking.TIME_COAL) } val burnTime = contextIntProvider("long_burn", 6400) val speed = contextFloatProvider("fast_burn", 2f) val charcoal = Items.CHARCOAL { cookingFuel(burnTime, speed) } val coal = Items.COAL { cookingFuel(burnTime = 200, speedMultiplier = 1.5f) // cooking_fuel={burn_time:200,speed_multiplier:1.5f} } val mixed = Items.BLAZE_ROD { cookingFuel(resolvableInt(ContextIntProviders.Cooking.TIME_COAL), resolvableFloat(2f)) } val dust = Items.BLAZE_POWDER { brewingFuel(ContextFloatProviders.Brewing.SPEED_DEFAULT, ContextIntProviders.Brewing.USES_DEFAULT) } val crystal = Items.AMETHYST_SHARD { brewingFuel(speedMultiplier = 2f, uses = 20) // brewing_fuel={speed_multiplier:2.0f,uses:20} } ``` ### Sign text `signTextFront` and `signTextBack` store the text of one side of a sign on an item, so a placed sign keeps it. Both take exactly 4 lines, one component each (anything else throws), and share the same options in their block: `color` (a `DyeColors`), `hasGlowingText` and `filteredMessages`, the 4 lines shown to players with the profanity filter on. ```kotlin val sign = Items.OAK_SIGN { signTextFront(text("Shop", Color.GOLD), text(), text("Open"), text()) { color = DyeColors.BLACK hasGlowingText = true } signTextBack(text("Closed"), text(), text(), text()) } ``` When a line is styled, every line is written as a compound, since a list holds a single type in NBT. ### Mob visibility `mobVisibility` scales the range at which mobs detect whoever carries the item, for the entity types and entity type tags it lists. `0.0` reduces the range to 2 blocks, `10.0` multiplies it by ten (values outside 0 to 10 throw), and stacked items never exceed `10.0`. ```kotlin val mask = Items.CARVED_PUMPKIN { mobVisibility(0f, EntityTypes.ENDERMAN, Tags.EntityType.SKELETONS) } ``` ### Villager food `villagerFood` makes villagers eat the item, restoring `nutrition` hunger (at least 1, otherwise it throws). ```kotlin val bread = Items.BREAD { villagerFood(2) } ``` ### Waxed `waxed` is an empty marker keeping a sign item waxed, so the placed sign can't be edited. ```kotlin val sign = Items.OAK_SIGN { signTextFront(text("Welcome"), text(), text(), text()) waxed() } ``` ### Profile The profile component can be either a player profile or a texture-based profile. #### Player Profile A player profile uses a player's name or UUID: ```kotlin Items.PLAYER_HEAD { playerProfile("Notch") } ``` #### Texture Profile A texture profile points at textures instead of a player. `texture` takes a `PlayerSkinTextureArgument` (the game's skins are in `Textures.Entity.Player.Slim` and `Textures.Entity.Player.Wide`), `elytra` an `ElytraTextureArgument` (`Textures.Entity.Equipment.Wings.ELYTRA`), `cape` a `CapeTextureArgument` and `model` the arm width: ```kotlin Items.PLAYER_HEAD { textureProfile(texture = Textures.Entity.Player.Slim.ALEX, model = MannequinModel.SLIM) } ``` A texture from a resource pack is given as a `namespace:path` string, a bare path stays in `minecraft`: ```kotlin Items.PLAYER_HEAD { textureProfile(texture = "mypack:skins/bob", cape = "mypack:capes/guild") } ``` ### Recipes result with components You can define recipes with components as well. Here's an example of crafting a custom enchanted golden apple using a shaped recipe: ```kotlin recipes { craftingShaped("enchanted_golden_apple") { pattern( "GGG", "GAG", "GGG" ) key("G", Items.GOLD_BLOCK) key("A", Items.APPLE) result(Items.ENCHANTED_GOLDEN_APPLE { food(nutrition = 10, saturation = 5.0f) consumable(consumeSeconds = 1.6f, animation = ConsumeAnimation.EAT, sound = SoundEvents.Entity.Generic.EAT) { onConsumeEffects { applyEffects( probability = 1f, Effect( id = Effects.REGENERATION, duration = 40, amplifier = 1, ambient = true, showParticles = true, showIcon = true ) ) } } }) } } ``` `onConsumeEffects` also takes `teleportRandomly(diameter, directionalParticles)`, where `directionalParticles` (`true` when omitted) sets whether the teleport particles follow the direction of the move: ```kotlin consumable(consumeSeconds = 1.6f, animation = ConsumeAnimation.EAT, sound = SoundEvents.Entity.Generic.EAT) { onConsumeEffects { teleportRandomly(diameter = 8f, directionalParticles = false) } } ``` ## Example Usage To give yourself an item with custom components using the `/give` command, you can define the item and its components as shown in the following example: ```kotlin import io.github.ayfri.kore.generated.Items import io.github.ayfri.kore.utils.set // Define the item with a custom name val customStone = Items.STONE { damageResistant(Tags.DamageType.IS_FIRE) customName(textComponent("Special Stone", Color.AQUA)) rarity(Rarities.EPIC) lore( textComponent("A stone with special properties.", Color.GRAY) + text("Use it wisely!", Color.GRAY) ) } // Use the /give command to give the item to yourself give(self(), customStone) ``` This example creates a custom stone item with a special name "Special Stone" in aqua color and gives it to the player using the `/give` command. ### Full list of Item components Below is an alphabetical list of all item component helpers available in Kore. The names match the DSL functions you call inside an `Items.* { }` builder. | Helper | Description | |--------------------------------------|----------------------------------------------------------------------------------------------------------| | `additionalTradeCost(..)` | Sets an extra emerald cost added on top of the base price for villager trades. | | `attackAnimation(..)` | Sets the arm-swing animation (`whack`, `stab` or `none`) and its duration (0 or more) when attacking. | | `attackRange(..)` | Configures the attack range of an item (min/max reach, hitbox margin, mob factor). | | `attributeModifiers(..)` | Modifies entity attributes (e.g., attack damage, speed, armor) when the item is equipped or held. | | `bannerPatterns(..)` | Defines the layered patterns displayed on a banner or shield. | | `baseColor(..)` | Sets the base color of a banner before patterns are applied. | | `bees { .. }` | Stores bee entities inside a beehive or bee nest item. | | `blockEntityData(..)` | Attaches custom NBT data to a block entity when the item is placed. | | `blocksAttacks(..)` | Configures how the item blocks incoming attacks when used (like a shield). | | `blockState(..)` | Sets block state properties (e.g., facing, powered) when the item is placed. | | `blockTransformer(..)` | Turns the block the item is used on into another one (strip logs, scrape or wax copper, till dirt). | | `breakSound(..)` | Specifies the sound played when the item breaks from durability loss. | | `brewingFuel(..)` | Makes the item a brewing stand fuel, with a speed and a number of brews, as numbers or provider files. | | `bucketEntityData(..)` | Stores entity data for mobs captured in buckets (e.g., fish, axolotl). | | `bundleContents(..)` | Defines the items stored inside a bundle. | | `canBreak(..)` | Restricts which blocks this item can break in Adventure mode. | | `canPlaceOn(..)` | Restricts which blocks this item can be placed on in Adventure mode. | | `chargedProjectiles(..)` | Stores projectiles loaded into a crossbow. | | `compostable(..)` | Makes the item usable in a composter, adding the layers of a number or a context int provider file. | | `consumable(..) { .. }` | Makes the item consumable with configurable eating time, animation, sound, and effects. | | `container(..)` | Stores items inside a container item (e.g., shulker box). | | `containerLoot(..)` | References a loot table to generate container contents when opened. | | `cookingFuel(..)` | Makes the item a furnace fuel, with a burn time and a cooking speed, as numbers or provider files. | | `customData(..)` | Attaches arbitrary custom NBT data for use by datapacks or mods. | | `customModelData(..)` | Provides numeric values for custom item model selection in resource packs. | | `customName(..)` | Sets a custom display name for the item (supports text components). | | `damage(..)` | Sets the current damage/durability consumed on a damageable item. | | `damageResistant(..)` | Makes the item entity resistant to specific damage types (e.g., fire, explosions). | | `damageType(..)` | Specifies the damage type dealt when attacking with this item. | | `deathProtection(..)` | Prevents death and applies effects when the holder would die (like a totem). | | `debugStickState(..)` | Stores the selected block state property for the debug stick per block type. | | `dye(..)` | Sets the dye color of an item using a `DyeColors` value. | | `dyedColor(..)` | Sets the dye color for leather armor or other dyeable items. | | `enchantable(..)` | Defines the enchantability value affecting enchantment quality at enchanting tables. | | `enchantmentGlintOverride(..)` | Forces the enchantment glint on or off regardless of enchantments. | | `enchantments(..)` | Applies enchantments with their levels to the item. | | `entityData(..)` | Stores entity NBT data for spawn eggs or items that spawn entities. | | `equippable(..)` | Configures equipment slot, sounds, and `EquipmentAssets` model when the item is worn. | | `fireworkExplosion(..)` | Defines a single firework star explosion shape, colors, and effects. | | `fireworks(..)` | Configures firework rocket flight duration and explosion effects. | | `food(..)` | Makes the item edible with nutrition, saturation, and optional effects. | | `glider()` | Enables elytra-like gliding when equipped in the chest slot. | | `instrument(..)` | Specifies the goat horn sound variant when the item is used. | | `intangibleProjectile()` | Makes projectiles from this item pass through entities without collision. | | `interactAnimation(..)` | Sets the arm-swing animation (`whack`, `stab` or `none`) and its duration (0 or more) when using it. | | `itemModel(..)` | Overrides the item's model with a custom model resource location. | | `itemName(..)` | Sets the item's base name (different from custom name; not italicized). | | `jukeboxPlayable(..)` | Allows the item to be played in a jukebox with a specified music disc track. | | `kineticWeapon(..) { .. }` | Configures kinetic weapon properties for mounted combat (damage multiplier, conditions). | | `lock(..)` | Locks a container so only players holding a matching item (item predicate) can open it. | | `lodestoneTarget(..)` | Makes a compass point to specific coordinates in a dimension. | | `lore(..)` | Adds tooltip lines below the item name for descriptions or flavor text. | | `mapDecorations(..)` | Adds custom icons/markers displayed on a filled map. | | `mapId(..)` | Links the item to a specific map data ID for filled maps. | | `maxDamage(..)` | Sets the maximum durability before the item breaks. | | `maxStackSize(..)` | Overrides how many items can stack in a single inventory slot (1-99). | | `minimumAttackCharge(..)` | Sets the minimum attack charge (0.0-1.0) required for full damage. | | `mobVisibility(..)` | Scales the range at which mobs of given entity types or tags detect the holder (0.0-10.0). | | `noteBlockSound(..)` | Specifies the sound a note block plays when this player head is above it. | | `ominousBottleAmplifier(..)` | Sets the Bad Omen effect amplifier (0-4) when consuming an ominous bottle. | | `piercingWeapon(..) { .. }` | Configures piercing weapon properties (knockback, dismount behavior). | | `playerProfile(..)` | Sets the player skin displayed on a player head item. | | `potDecorations(..)` | Defines the item stack on each face of a decorated pot (`back`, `left`, `right`, `front`). | | `potionContents(..)` | Configures potion color, effects, and custom potion mixtures. | | `potionDurationScale(..)` | Multiplies the duration of potion effects from this item. | | `providesBannerPatterns(..)` | Registers this item as a banner pattern source for the loom. | | `providesPotteryPattern(..)` | Sets the pattern this item shows on the face of a decorated pot. | | `providesTrimMaterial(..)` | Registers this item as an armor trim material for the smithing table. | | `rarity(..)` | Sets the item name color tier (common, uncommon, rare, epic). | | `recipes(..)` | Unlocks specified recipes when this knowledge book is used. | | `repairable(..)` | Defines which items can repair this item on an anvil. | | `repairCost(..)` | Sets the anvil repair cost penalty for combining or renaming. | | `signTextBack(..) { .. }` | Sets the text of the back of a sign, 4 lines with color, glow and filtered lines. | | `signTextFront(..) { .. }` | Sets the text of the front of a sign, 4 lines with color, glow and filtered lines. | | `storedEnchantments(..)` | Stores enchantments in an enchanted book for anvil application. | | `sulfurCubeContent(..)` | Stores the item held inside a sulfur cube. | | `suspiciousStewEffectsComponent(..)` | Defines the status effects applied when consuming suspicious stew. | | `tool { .. }` | Configures mining speeds, suitable blocks, and durability cost for tools. | | `tooltipDisplay(..)` | Controls which tooltip sections are shown or hidden. | | `tooltipStyle(..)` | Applies a custom tooltip background/border style from a resource pack. | | `trim(..)` | Applies an armor trim pattern and material to armor items. | | `unbreakable()` | Prevents the item from taking durability damage. | | `useCooldown(..)` | Applies a cooldown period after using this item. | | `useEffects(..)` | Configures use effects like allowing sprinting, interacting vibrations and speed multiplier while using. | | `useRemainder(..)` | Specifies an item left behind after this item is fully consumed. | | `villagerFood(..)` | Makes villagers eat the item, restoring the given nutrition. | | `waxed()` | Keeps a sign item waxed, so the placed sign can't be edited. | | `weapon(..)` | Configures melee weapon properties like damage and attack speed. | | `writableBookContent(..)` | Stores editable pages in a book and quill. | | `writtenBookContent(..)` | Stores signed book content including title, author, and pages. | ## Works great with Inventory Manager If you build rich items with components and want to enforce them in player GUIs or chest slots, pair them with the [Inventory Manager](https://kore.ayfri.com/docs/helpers/inventory-manager.md). It lets you keep specific items in slots, react to takes, and clean up other slots while preserving all component data. ## Patch items When you need to patch components on existing stacks (set name/lore, toggle tooltips, edit container contents, etc.) at runtime, use [Item Modifiers](https://kore.ayfri.com/docs/data-driven/item-modifiers.md). Kore maps the vanilla functions like `set_components`, `set_contents`, `set_fireworks`, and more. ## Custom Component For a component Kore has no helper for (a modded one, or a brand-new vanilla one), wrap its raw NBT in a `CustomComponent` and store it under the component name. An extension on `ComponentsScope` gives it the same call syntax as the built-in helpers: ```kotlin package your.package import io.github.ayfri.kore.arguments.components.ComponentsScope import io.github.ayfri.kore.arguments.components.item.CustomComponent import io.github.ayfri.kore.arguments.types.resources.FunctionArgument import io.github.ayfri.kore.utils.nbt import io.github.ayfri.kore.utils.set fun ComponentsScope.use(function: FunctionArgument, damage: Int = 0, cooldown: Float = 0f) = apply { this["mymod:use"] = CustomComponent(nbt { this["function"] = function.asId() this["damage"] = damage this["cooldown"] = cooldown }) } ``` And here's how you can use this custom component in an item definition: ```kotlin import io.github.ayfri.kore.generated.Items import your.package.use val myFunction = function("use_weapon") { // Your function code here. } val customItem = Items.DIAMOND_SWORD { use(myFunction, damage = 4, cooldown = 1.5f) } // Result: // minecraft:diamond_sword[mymod:use={function:"datapack:use_weapon",damage:4,cooldown:1.5f}] ``` ## Entity Variant Components (25w04a+) > *Introduced in snapshot [25w04a](https://www.minecraft.net/en-us/article/minecraft-snapshot-25w04a)* > > Entity variants such as axolotl colours, cat collars or tropical-fish patterns are now exposed as **data components** and can be used on entities, spawn-egg items, mob buckets and paintings. This replaces the old `type_specific` NBT fields. Kore ships dedicated helpers for each of these components. You can attach them to an `Items.*` builder the exact same way you attach any other component: ```kotlin import io.github.ayfri.kore.arguments.enums.* import io.github.ayfri.kore.generated.Items import io.github.ayfri.kore.generated.PaintingVariants // Axolotl bucket with the blue variant val blueAxolotlBucket = Items.AXOLOTL_BUCKET { axolotlVariant(AxolotlVariants.BLUE) } // Cat spawn-egg with a red collar val redCollarCat = Items.CAT_SPAWN_EGG { catCollar(DyeColors.RED) } // Painting item selecting the "kebab" variant (namespace implied) val kebabPainting = Items.PAINTING { paintingVariant(PaintingVariants.KEBAB) } ``` These components can also be queried inside predicates: ```kotlin predicate("only_blue_axolotls") { entityProperties { components { axolotlVariant(AxolotlVariants.BLUE) } } } ``` The full list of variant helpers currently included in Kore is: - `axolotlVariant(..)` - `catCollar(..)` / `catVariant(..)` - `chickenVariant(..)` - `cowVariant(..)` - `cushionColor(..)` - `foxVariant(..)` - `frogVariant(..)` - `horseVariant(..)` - `llamaVariant(..)` - `mooshroomVariant(..)` - `paintingVariant(..)` - `parrotVariant(..)` - `pigVariant(..)` - `rabbitVariant(..)` - `salmonSize(..)` - `sheepColor(..)` - `shulkerColor(..)` - `tropicalFishBaseColor(..)` / `tropicalFishPattern(..)` / `tropicalFishPatternColor(..)` - `villagerVariant(..)` - `wolfCollar(..)` / `wolfSoundVariant(..)` / `wolfVariant(..)` - `zombieNautilusVariant(..)` They follow the exact same naming and DSL pattern you already know: ```kotlin fun ComponentsScope.wolfVariant(variant: WolfVariants) { /*…*/ } ``` Because the logic lives in regular data components, you automatically get: - Compatibility with the `itemStack` / `Items.*` DSL - Predicate support through `components {}` - Correct serialization back to the vanilla command and NBT syntax Feel free to mix several variant components on the same `ComponentsScope`: ```kotlin Items.WOLF_SPAWN_EGG { wolfCollar(DyeColors.BLACK) wolfVariant(WolfVariants.SNOWY) } ``` ## Component Matchers & Item Predicates Kore provides powerful tools for matching and filtering items based on their components. This is useful in predicates, execute conditions, and loot tables. There are two distinct forms: - **Item predicates** (`.predicate { }` / `itemPredicate { }`) produce the inline command syntax `[predicate]`, used anywhere an item argument is accepted - `/give`, `/clear`, the `items` selector, `execute if items`. - **Component matchers** (`predicates { }` inside `matchTool { }`, or `subPredicates { }` inside `.predicate { }`) check the same components from within a predicate *file* - see [Item Predicates](https://kore.ayfri.com/docs/data-driven/predicates.md#item-predicates) and [Item Sub-Predicates](https://kore.ayfri.com/docs/data-driven/predicates.md#item-sub-predicates) in the Predicates guide for how they plug into a full predicate. Both forms share the same set of component checks - see [Available Component Matchers](#available-component-matchers) below for the full list. ### Item Predicates Item predicates let you filter items by their components using the command syntax `[predicate]`: ```kotlin import io.github.ayfri.kore.arguments.components.* import io.github.ayfri.kore.arguments.components.item.* import io.github.ayfri.kore.generated.Items import io.github.ayfri.kore.generated.ItemComponentTypes // Match items with specific component values val damagedSword = Items.DIAMOND_SWORD.predicate { damage(10) } // Result: minecraft:diamond_sword[damage=10] // Match any item with a component present (existence check) val hasInstrument = itemPredicate { isPresent(ItemComponentTypes.INSTRUMENT) } // Result: *[instrument] // Partial matching with ~ syntax val customDataMatch = Items.STONE.predicate { customData { this["myKey"] = "myValue" } partial(ItemComponentTypes.CUSTOM_DATA) } // Result: minecraft:stone[custom_data~{myKey:"myValue"}] // Negated predicates (component must NOT have this value) val notDamaged = Items.DIAMOND_SWORD.predicate { !damage(0) } // Result: minecraft:diamond_sword[!damage=0] // Multiple alternatives with OR val multipleValues = Items.STONE.predicate { damage(1) or damage(2) or damage(3) } // Result: minecraft:stone[damage=1|damage=2|damage=3] // Count predicate val stackOf10 = Items.DIAMOND.predicate { count(10) } // Result: minecraft:diamond[count=10] ``` #### Practical Example: Clearing Items by Name A common vanilla pattern is clearing every item with a specific `item_name`, regardless of its item type - the raw command looks like `clear @s *[minecraft:item_name="Blank"] 2`. It breaks down into three pieces: `@s` is the target, `*[minecraft:item_name="Blank"]` is an item predicate matching **any** item (`*`) whose `item_name` component equals `"Blank"`, and `2` is the max count to remove. Build the same thing with Kore's `clear` command and `itemPredicate { }`: ```kotlin import io.github.ayfri.kore.commands.clear import io.github.ayfri.kore.arguments.types.literals.self function("clear_blank_items") { clear(self(), itemPredicate { itemName("Blank") }, 2) } ``` This generates `clear @s *[item_name="Blank"] 2`. Because no `ItemArgument` is passed to `itemPredicate { }`, it defaults to `*` (any item) - pass an item to `.predicate { }` instead (e.g. `Items.PAPER.predicate { itemName("Blank") }`) if you want to restrict the match to a specific item type too. ### Component Matchers (Sub-Predicates) For matching logic beyond a plain item predicate, use the `predicates { }` builder inside `matchTool { }` (or `subPredicates { }` inside `.predicate { }`) with component matchers: ```kotlin import io.github.ayfri.kore.arguments.components.matchers.* import io.github.ayfri.kore.arguments.numbers.ranges.rangeOrInt predicate("upgradeable_pickaxe") { matchTool { items(Items.DIAMOND_PICKAXE) predicates { // Match damage component with range damage { durability = rangeOrInt(1..100) damage = rangeOrInt(0..10) } // Match enchantments enchantments { enchantment(Enchantments.SHARPNESS, level = 3) } // Match potion contents potionContents(Potions.SWIFTNESS, Potions.STRENGTH) } } } ``` `potionContents` matches the potions of the item, given as potions or a potion tag, and its active effects. The block form sets both `potions` and `effects`, `effects` taking the same `contains`, `countElement` and `size` checks as the other collection matchers. Each element is a map of mob effects to a `mobEffectPredicate`, like the entity `effects` predicate: ```kotlin import io.github.ayfri.kore.features.predicates.sub.mobEffectPredicate predicates { potionContents { potions(Potions.SWIFTNESS, Potions.STRONG_SWIFTNESS) effects { contains(mapOf(Effects.SPEED to mobEffectPredicate { amplifier = rangeOrInt(1) })) } } } ``` ### Existence Checks You can check if a component exists on an item without matching a specific value. In an item predicate (command form), use `isPresent`: ```kotlin val hasInstrument = itemPredicate { isPresent(ItemComponentTypes.INSTRUMENT) } // Result: *[instrument] ``` Inside a `predicates { }` / `subPredicates { }` block, use `exists`: ```kotlin predicate("has_instrument") { matchTool { predicates { exists(ItemComponentTypes.INSTRUMENT) exists(ItemComponentTypes.DAMAGE) } } } ``` ### Available Component Matchers | Matcher | Description | |---------------------------|------------------------------------------------| | `attributeModifiers { }` | Match attribute modifier properties | | `bundleContents { }` | Match bundle contents | | `container { }` | Match container slot contents | | `customData { }` | Match custom NBT data | | `damage { }` | Match damage/durability values | | `enchantments { }` | Match enchantment types and levels | | `exists(component)` | Check if component exists (empty `{}` matcher) | | `fireworkExplosion { }` | Match firework star properties | | `fireworks { }` | Match firework rocket properties | | `jukeboxPlayable { }` | Match jukebox song | | `potionContents(..)` | Match potions, a potion tag or active effects | | `storedEnchantments { }` | Match stored enchantments (enchanted books) | | `trim { }` | Match armor trim pattern/material | | `villagerVariant(..)` | Match the villager type of an entity | | `writableBookContent { }` | Match book pages | | `writtenBookContent { }` | Match signed book content | ### Complete Example: Custom Tool Upgrade System Here's a practical example showing how to use item predicates to create a tool upgrade system that detects enchanted, damaged tools and replaces them with upgraded versions: ```kotlin dataPack("tool_upgrades") { // Predicate to find diamond swords that need upgrading predicate("upgradeable_sword") { matchTool { items(Items.DIAMOND_SWORD) predicates { // Must have Sharpness enchantment enchantments { enchantment(Enchantments.SHARPNESS, level = rangeOrInt(1..4)) } // Must be damaged (durability used) damage { damage = rangeOrInt(1..1000) } } } } // Swaps the item id while keeping every component, enchantments included val upgradeToNetherite = itemModifier("upgrade_to_netherite") { setItem(Items.NETHERITE_SWORD) } // Function to check player's held item and upgrade it function("check_upgrade") { // Check if holding an upgradeable sword execute { ifCondition { items( self(), WEAPON.MAINHAND, Items.DIAMOND_SWORD.predicate { subPredicates { enchantments { enchantment(Enchantments.SHARPNESS, level = rangeOrInt(3..4)) } } } ) } run { // Replace with netherite sword keeping enchantments items.modify(self(), WEAPON.MAINHAND, upgradeToNetherite) tellraw(self(), textComponent("Your sword has been upgraded!", Color.GOLD)) } } } // Clear specific items from inventory using predicates function("clear_broken_tools") { // Clear any tool with 1 durability left clear(allPlayers(), itemPredicate { subPredicates { damage { durability = rangeOrInt(1) } } }) } // Give reward only if player has specific item combination function("check_collection") { execute { // Check for a goat horn (any variant) ifCondition { items( self(), INVENTORY, itemPredicate { isPresent(ItemComponentTypes.INSTRUMENT) } ) } // Check for enchanted book with Mending ifCondition { items( self(), INVENTORY, Items.ENCHANTED_BOOK.predicate { subPredicates { storedEnchantments { enchantment(Enchantments.MENDING) } } } ) } run { give(self(), Items.NETHER_STAR) } } } } ``` ## Conclusion Components are a powerful tool for customizing Minecraft objects, and the Kore library makes it easier than ever to work with these components programmatically. Whether you're adding custom attributes, enchantments, or creating complex items with multiple components, Kore provides a robust and intuitive API for enhancing your Minecraft experience. By following the examples and practices outlined in this article, you can leverage the full potential of components in your Minecraft projects, creating richer and more engaging content for players. Happy crafting! ## See Also - [Predicates](https://kore.ayfri.com/docs/data-driven/predicates.md) - Use components in predicate conditions; see [Item Predicates](https://kore.ayfri.com/docs/data-driven/predicates.md#item-predicates) and [Item Sub-Predicates](https://kore.ayfri.com/docs/data-driven/predicates.md#item-sub-predicates) for how the matchers on this page plug into a full `predicate { }` file - [Item Modifiers](https://kore.ayfri.com/docs/data-driven/item-modifiers.md) - Patch components at runtime - [Recipes](https://kore.ayfri.com/docs/data-driven/recipes.md) - Use components in recipe results - [Inventory Manager](https://kore.ayfri.com/docs/helpers/inventory-manager.md) - Enforce component-rich items in slots ### External Resources - [Minecraft Wiki: Data component format](https://minecraft.wiki/w/Data_component_format) - Official component reference