Default Component Formats

CustomMarker

ID: abyssallib:marker

An internal identifier utilized strictly by the library to track custom items. Do not manually define or modify this component in your configuration files.

BlockItem

ID: abyssallib:block_item

Maps an item specifically to a registered Custom Block. When a player places an item containing this component, the specified custom block will be placed in the world.

Format: Requires a single string representing the registered ID of the custom block.

ItemAttributeModifier

ID: minecraft:attribute_modifiers

Applies specific attribute modifiers (e.g., Attack Damage, Movement Speed) when the item is equipped or held.

Format: Requires a normal map where the top-level keys are the namespaced Attribute IDs. The inner map uses the equipment slot group as the key, mapped to the modifier data object.

• key: The unique namespaced key of the modifier.

• amount: The numeric value of the modifier.

• operation: Any valid Bukkit AttributeModifier.Operation enum name (e.g., ADD_NUMBER, ADD_SCALAR, MULTIPLY_SCALAR_1).

• slot: The equipment slot group (MAINHAND, OFFHAND, ANY, ARMOR, etc.). Note that this should match the key of the inner map.

BannerPatterns

ID: minecraft:banner_patterns

Defines the layered patterns applied to a banner or shield item.

Format: Requires a list of pattern objects defining a color and a pattern type.

• color: A standard DyeColor name (e.g., RED, LIGHT_BLUE).

• pattern: The namespaced key of the banner pattern (e.g., minecraft:skull, minecraft:creeper).

BlockAttacks

ID: minecraft:blocks_attacks

Configures the item's ability to block incoming attacks, functioning similarly to a shield.

Format: Requires an object defining the blocking behavior, cooldowns, and damage reduction rules.

• block_delay_seconds: The delay before the block becomes active.

• disable_cooldown_scale: Cooldown multiplier applied if the block is disabled.

• damage_reductions: List of reduction rules for specific damage types.

• item_damage: Function dictating how the item takes durability damage.

• bypassed_by: (Optional) A list of damage type keys that bypass this block.

• block_sound/disable_sound: (Optional) Sound event keys.

BlockData

ID: minecraft:block_data

(Currently unusable/unimplemented in the Codec API)

BreakSound

ID: minecraft:break_sound

Defines the sound event played when the item's durability reaches zero and it breaks.

Format: Requires a single string representing the sound event key.

BundleContent

ID: minecraft:bundle_contents

Defines the inventory contents stored within a bundle item.

Format: Requires a list of serialized ItemStack objects. Items can be defined simply by their string ID, or fully expanded to include amount and nested data components.

CanBreak

ID: minecraft:can_break

Allows the item to break specific blocks when the player is in Adventure mode.

Format: Requires a list of block predicates. Because this relies on Paper's ItemAdventurePredicate—which evaluates a list of multiple predicates rather than a single flat list of blocks—this is represented as a list of arrays. Each inner array represents a single predicate containing the namespaced keys of the blocks it matches.

CanPlaceOn

ID: minecraft:can_place_on

Allows the item (if it is a block) to be placed on top of specific blocks when the player is in Adventure mode.

Format: Requires a list of block predicates. Just like can_break, this uses Paper's nested predicate system. It expects a list of arrays, where each inner array contains the namespaced block keys for that specific predicate.

ChargedProjectiles

ID: minecraft:charged_projectiles

Defines the loaded projectiles within a crossbow item.

Format: Requires a list of serialized ItemStack objects. Projectiles can be defined simply by their string ID, or fully expanded to include amount and nested data components.

CustomData

ID: minecraft:custom_data

Attaches arbitrary data (equivalent to vanilla custom NBT) to the item. This is incredibly useful for storing custom plugin values that don't fit into standard components.

Format: Requires a standard map of key-value pairs. Values can be strings, booleans, numbers, lists, or nested maps.

Consumable

ID: minecraft:consumable

Defines how an item is consumed (e.g., eaten or drunk) and the effects applied to the player upon consumption.

Format: Requires an object defining the consumption parameters and a list of consume_effects.

• consume_seconds: The time in seconds it takes to consume the item.

• animation: The animation type (NONE, EAT, DRINK, BLOCK, BOW, SPEAR, CROSSBOW, SPYGLASS, TOOT_HORN, BRUSH).

• sound: The namespaced key of the sound event played during consumption.

• has_consume_particles: Whether the item emits particles while being consumed.

• consume_effects: A list of effect objects. Valid types are apply_effects, remove_effects, clear_all_effects, teleport_randomly, and play_sound.

Full Example:

ContainerLoot

ID: minecraft:container_loot

Links the item (usually a container like a chest or shulker box) to a specific loot table, which will dynamically generate its contents upon placement or opening.

Format: Requires an object containing the namespaced loot_table key and a seed. Provide 0 as the seed to randomize the loot generation.

UseCooldown

ID: minecraft:use_cooldown

Applies a visual and mechanical cooldown to the item immediately after it is used.

Format: Requires the cooldown duration in seconds, and an optional group key to link cooldowns across multiple items (for example, applying a single cooldown group to all Ender Pearls).

CustomName

ID: minecraft:custom_name

Overrides the display name of the item.

Format: Requires a single string formatted using standard MiniMessage tags.

DeathProtection

ID: minecraft:death_protection

Configures the item to act as a Totem of Undying, defining the effects applied to the player when the item saves them from death.

Format: Requires a list of ConsumeEffect objects. These share the exact same structure as the consume_effects list documented in the minecraft:consumable component.

DisplayTooltip

ID: minecraft:tooltip_display

Controls whether the item's tooltip is hidden entirely, or selectively hides specific component data from appearing in the tooltip.

Format: Requires an object containing a boolean to hide the tooltip globally, and a list of specific components to hide.

• hide_tooltips: If true, completely hides the entire item tooltip.

• hidden_components: A list of namespaced component keys (e.g., minecraft:unbreakable, minecraft:enchantments) that should not be rendered in the item's lore.

Durability

ID: minecraft:damage

Defines the current amount of damage the item has taken. (Note: To define the maximum durability of an item, you must use the minecraft:max_damage component instead).

Format: Requires a single integer representing the damage value.

Dye

ID: minecraft:dye

Applies a base dye color to applicable items (like Leather Armor, Wolf Armor, or glass).

Format: Requires a single string matching a standard Bukkit DyeColor name (e.g., WHITE, ORANGE, MAGENTA, LIGHT_BLUE).

DyedColor

ID: minecraft:dyed_color

Applies a specific ARGB color tint to dyeable items, allowing for precise custom colors beyond the standard vanilla dye variants.

Format: Requires an object defining the exact alpha, red, green, and blue color channels. Values must be integers between 0 and 255.

Enchantable

ID: minecraft:enchantable

Defines the item's base enchantability value, which determines the quality and quantity of enchantments it receives when placed in an Enchanting Table. For reference, Diamond tools have an enchantability of 10, while Gold tools have 22.

Format: Requires a single integer representing the enchantability value.

EnchantmentGlintOverride

ID: minecraft:enchantment_glint_override

Forces the glowing visual enchantment glint on or off.

Format: Requires a single boolean value. If true, the item will always glow even without enchantments. If false, the item will never glow, even if it has enchantments applied.

Enchantments

ID: minecraft:enchantments

Defines the enchantments applied to the item.

Format: Requires a normal map where the keys are the namespaced enchantment IDs and the values are their respective levels as integers.

Equippable

ID: minecraft:equippable

Dictates how the item can be equipped, the slot it occupies, and associated sounds, models, and behavioral rules.

Format: Requires an object defining the equipment properties.

• slot: The Bukkit EquipmentSlot enum name (e.g., HEAD, CHEST, LEGS, FEET, BODY, HAND, OFF_HAND).

• equip_sound: The namespaced key of the sound played when equipped.

• asset_id: (Optional) The namespaced key for the armor model/texture asset.

• camera_overlay: (Optional) The namespaced key for a first-person screen overlay (like carved pumpkins).

• allowed_entities: (Optional) A list of namespaced entity types allowed to equip this item.

• dispensable: Boolean determining if dispensers can equip this item onto targets.

• swappable: Boolean determining if the player can equip it via right-click to swap.

• damage_on_hurt: Boolean determining if the item loses durability when the wearer takes damage.

• can_be_sheared: Boolean determining if the item can be removed by shears.

• shear_sound: (Optional) The namespaced key of the sound played when sheared.

Fireworks

ID: minecraft:fireworks

Defines the properties of a firework rocket, including its flight duration and the explosive effects it produces upon detonating.

Format: Requires an object defining the duration and a list of effect objects.

• flight_duration: Integer representing the flight time modifier.

• effects: A list of explosion effect objects (see minecraft:firework_explosion below for the exact structure).

FireworkExplosion

ID: minecraft:firework_explosion

Defines a single firework explosion effect. This is typically applied directly to Firework Star items.

Format: Requires an object defining the visual shape, toggles, and colors.

• type: The Bukkit FireworkEffect.Type (e.g., BALL, BALL_LARGE, STAR, CREEPER, BURST).

• flicker: Boolean to enable the crackle effect.

• trail: Boolean to enable the trailing tail effect.

• colors: A list of ARGB color objects defining the primary explosion colors.

• fade_colors: A list of ARGB color objects the explosion fades into.

Food

ID: minecraft:food

Defines the core nutritional properties of an edible item. (Note: The actual consumption speed, animation, and potion effects are handled by the minecraft:consumable component, not here).

Format: Requires an object defining nutrition points and saturation.

• nutrition: Integer representing the food points (half-drumsticks) restored.

• saturation: Float representing the saturation modifier applied.

• can_always_eat: Boolean. If true, the player can eat this item even when their hunger bar is full (e.g., Golden Apples).

Glider

ID: minecraft:glider

Equips the item with Elytra gliding capabilities when worn in the chest slot.

Format: This is a presence component. It does not require any specific data, so it is defined using an empty object or empty string based on the codec.

Instrument

ID: minecraft:instrument

Defines the specific music instrument sound played when the item (typically a Goat Horn) is used.

Format: Requires a single string representing the namespaced key of the instrument (e.g., minecraft:ponder_goat_horn, minecraft:sing_goat_horn).

IntangibleProjectile

ID: minecraft:intangible_projectile

Marks a projectile item (like an arrow) as intangible, meaning it can only be picked up by players in Creative mode after being fired.

Format: This is a presence component. It is defined using an empty string.

ItemModel

ID: minecraft:item_model

Overrides the default visual model of the item to point to a specific model definition in a resource pack.

Format: Requires a single string representing the namespaced key of the model.

ItemName

ID: minecraft:item_name

Overrides the base name of the item. Unlike minecraft:custom_name, this does not automatically italicize the text and is treated as the item's true, inherent name.

Format: Requires a single string formatted using standard MiniMessage tags.

Lore

ID: minecraft:lore

Defines the lore (description lines) displayed beneath the item's name.

Format: Requires a list of strings, each formatted using standard MiniMessage tags.

MapColor

ID: minecraft:map_color

Defines the ambient color of a filled map item.

Format: Requires an object defining the exact alpha, red, green, and blue color channels. Values must be integers between 0 and 255.

MapDecorates

ID: minecraft:map_decorations

Defines specific markers and decorations (like player icons, banners, or frames) that appear on a filled map.

Format: Requires a map where the top-level keys are arbitrary string identifiers for the decoration. Each key maps to a decoration entry object.

• type: The namespaced key of the map cursor type (e.g., minecraft:player, minecraft:target_x, minecraft:red_x).

• x: Double representing the X coordinate on the map.

• z: Double representing the Z coordinate on the map.

• rotation: Float representing the rotation of the icon.

MapID

ID: minecraft:map_id

Links a filled map item to its specific map state data stored on the server.

Format: Requires a single integer representing the map's ID.

MapPostProcess

ID: minecraft:map_post_processing

Defines the post-processing instruction for a filled map, typically used to lock or scale maps in a cartography table.

Format: Requires a single string matching a valid Bukkit MapPostProcessing enum (e.g., LOCK, SCALE).

MaxDurability

ID: minecraft:max_damage

Defines the maximum durability (damage capacity) of an item.

Format: Requires a single integer representing the maximum damage the item can take before breaking.

MaxStackSize

ID: minecraft:max_stack_size

Defines the maximum amount of this item that can be stacked in a single inventory slot.

Format: Requires a single integer. In modern vanilla, this value can typically be set anywhere from 1 to 99.

ModelData

ID: minecraft:custom_model_data

Applies custom model data to an item. This is actively used by resource packs to determine which 3D model or texture to render.

Format: Requires an object defining lists of floats, flags (booleans), strings, and colors (ARGB objects).

NoteBlockSound

ID: minecraft:note_block_sound

Defines the sound played when this item (typically a player head or skull) is placed on top of a Note Block.

Format: Requires a single string representing the namespaced sound event key.

OminousAmplifier

ID: minecraft:ominous_bottle_amplifier

Defines the amplifier level for an Ominous Bottle, which directly translates to the level of the Bad Omen effect applied when consumed.

Format: Requires a single integer between 0 and 4 (representing Bad Omen I through V).

PlayableJukebox

ID: minecraft:jukebox_playable

Makes the item playable in a Jukebox and defines which specific song it will play.

Format: Requires a single string representing the namespaced key of a registered Jukebox song.

PotDecorates

ID: minecraft:pot_decorations

Defines the specific items (usually pottery sherds or bricks) adorning the four sides of a Decorated Pot item.

Format: Requires an object mapping the front, back, left, and right sides to specific namespaced item keys.

PotionContent

ID: minecraft:potion_contents

Defines the base potion type, custom liquid color, and specific custom status effects stored within a potion, splash potion, lingering potion, or tipped arrow.

Format: Requires an object defining the potion base type, an optional ARGB color, an optional customName for the potion, and a list of customEffects (sharing the format of minecraft:potion_effect).

PotionDurationScale

ID: minecraft:potion_duration_scale

A multiplier applied to the duration of any potion effects granted by this item. This is primarily used by Ominous Bottles and custom Tipped Arrows to dynamically scale effect lengths.

Format: Requires a single float representing the scale multiplier.

Profile

ID: minecraft:profile

Defines the player profile tied to a Player Head item, determining its skin/texture.

Format: Requires an object defining the player's name, UUID, and/or texture properties. All fields are technically optional, but a valid texture requires at least the properties list to be populated with the base64 texture string.

• name: (Optional) The username of the player.

• uuid: (Optional) The UUID of the player.

• properties: A list of property objects containing name, value (the base64 string), and an optional signature.

Recipes

ID: minecraft:recipes

Defines a list of recipes contained within a Knowledge Book item. Upon using the book, these recipes are granted to the player.

Format: Requires a list of strings representing the namespaced keys of the recipes to grant.

RemainderUse

ID: minecraft:use_remainder

Defines the item left behind after this item is consumed (e.g., the empty Glass Bottle left behind after drinking a Potion).

Format: Requires a serialized ItemStack object. This can be a simple string ID, or an expanded object including amount and nested data components.

Repairable

ID: minecraft:repairable

Defines the specific items that can be used in an anvil to repair this item's durability.

Format: Requires a list of strings representing the namespaced item keys that are valid repair materials.

RepairCost

ID: minecraft:repair_cost

Defines the current cumulative anvil penalty cost for the item.

Format: Requires a single integer representing the level cost.

ResistantDamage

ID: minecraft:damage_resistant

Makes the item completely immune to specific types of damage when dropped on the ground (e.g., how Netherite items do not burn in lava).

Format: Can be defined as a single string, or a list of strings representing the namespaced keys of the damage types to resist.

ShulkerColor

ID: minecraft:shulker_color

Overrides the base color of a Shulker Box item.

Format: Requires a single string matching a standard Bukkit DyeColor name (e.g., WHITE, PURPLE, BLACK).

StoredEnchantments

ID: minecraft:stored_enchantments

Defines the enchantments stored inside an Enchanted Book. These do not apply to the book itself, but rather dictate what can be transferred via an anvil.

Format: Requires a normal map where the keys are the namespaced enchantment IDs and the values are their respective levels as integers.

SuspiciousStewEffect

ID: minecraft:suspicious_stew_effect

Defines the hidden status effects granted to a player upon consuming this Suspicious Stew item.

Format: Requires a list of effect objects, each containing an effect_type and a duration.

• effect_type: The namespaced key of the potion effect.

• duration: The length of the effect in ticks (20 ticks = 1 second).

Tool

ID: minecraft:tool

Defines the item's behavior when used to mine blocks, including base mining speed, durability taken per block, and specific mining rules for different block types.

Format: Requires an object defining the default tool parameters and a list of specific mining rules.

• default_mining_speed: Float representing the base mining speed multiplier (1.0 is default).

• damage_per_block: Integer representing the durability lost per block mined.

• can_destroy_blocks_in_creative: Boolean determining if it breaks blocks instantly in Creative mode.

• rules: A list of rule objects containing:

  • blocks: A list of namespaced block keys this rule applies to.

  • speed: The mining speed multiplier for these specific blocks.

  • correct_for_drops: A TriState string (TRUE, FALSE, NOT_SET) determining if mining these blocks yields their standard drops.

TooltipStyle

ID: minecraft:tooltip_style

Overrides the visual background and styling of the item's tooltip UI.

Format: Requires a single string representing the namespaced key of the GUI sprite/texture.

TrackerLodestone

ID: minecraft:lodestone_tracker

Links a compass item to a specific location, typically a Lodestone, causing the compass needle to point toward it.

Format: Requires an object defining the target location and whether the compass is actively being tracked.

• tracked: Boolean. If true, the compass will lose its target if the lodestone block is broken.

• location: A serialized Location object requiring world (namespaced key), x, y, z, yaw, and pitch.

Trim

ID: minecraft:trim

Applies an armor trim to the item, altering its visual texture.

Format: Requires an object defining the material (color) and pattern (design) of the trim.

• material: The namespaced key of the trim material (e.g., minecraft:quartz, minecraft:gold, minecraft:amethyst).

• pattern: The namespaced key of the trim pattern (e.g., minecraft:silence, minecraft:ward, minecraft:coast).

Unbreakable

ID: minecraft:unbreakable

Makes the item completely immune to durability loss.

Format: This is a presence component. It does not require any specific data and is defined using an empty string.

Weapon

ID: minecraft:weapon

Defines the item's combat properties when used to attack an entity.

Format: Requires an object defining the durability loss and shield-disabling mechanics.

• item_damage_per_attack: Integer representing the durability lost when striking an entity.

• disable_blocking_for_seconds: Float representing how long (in seconds) the target's shield is disabled if they block the attack.

WritableBookContents

ID: minecraft:writable_book_content

Defines the raw text content of a Book and Quill item.

Format: Requires a list of strings, where each string represents a single page of raw text.

WrittenBookContents

ID: minecraft:written_book_content

Defines the properties and read-only content of a Written Book item.

Format: Requires an object defining the book's metadata and a list of formatted pages.

• title: The title of the book.

• author: The author's name.

• generation: Integer representing the book's copy status (0 = Original, 1 = Copy, 2 = Copy of a Copy, 3 = Tattered).

• resolved: Boolean determining if the text components inside have already been parsed.

• pages: A list of strings formatted using standard MiniMessage tags.