Skip to content

ItemStack (ItemStackReader)

Jump to bottom
Luis Benavides-Naranjo edited this page Aug 1, 2025 · 4 revisions

Introduction

BlobLib allows constructing items directly from YAML files. This is useful in cases such as TranslatableItem (having items that translate during runtime) and BlobInventory (user interfaces used in plugins that allow server administrators to customize them to their liking, even translating during runtime).

Material

Enchantment

ItemFlag

Attribute

Attribute Operation (AttributeModifier.Operation)

Table of Contents

  1. YAML File Structure

  2. Configuration Options

  3. Example Configuration

YAML File Structure

Material: "DIAMOND_SWORD"
Amount: 1
# ... other options ...

All options are optional except Material. Unspecified fields use plugin defaults.

Configuration Options

Below is a comprehensive list of fields you can set for each custom item:

Material

  • Type: String
  • Required: Yes
  • Description: The base material for the item. Must be a valid Material enum, e.g., STONE, DIAMOND_PICKAXE. For player heads, use HEAD-<base64_url>.

Amount

  • Type: Integer
  • Required: No
  • Default: 1
  • Range: 1 to 127
  • Description: Stack size of the item.

Damage & Durability

Damage

  • Type: Integer
  • Required: No
  • Default: 0
  • Description: Initial damage value for tools/armor.

RepairCost

  • Type: Integer
  • Required: No
  • Default: 0
  • Description: Repair cost applied when an anvil is used.

ArmorTrim

  • Type: Section

  • Required: No

  • Fields:

    • TrimMaterial (String): Key of the trim material.
    • TrimPattern (String): Key of the trim pattern.

  • Description: Applies a visual trim to armor items.

ItemName

  • Type: String
  • Required: No
  • Description: Custom display name, supports standard '&' color codes (e.g., &6Excalibur).

HideToolTip

  • Type: Boolean
  • Required: No
  • Default: false
  • Description: Hides the tooltip on hover.

EnchantmentGlintOverride

  • Type: Boolean
  • Required: No
  • Default: false
  • Description: Toggles the enchantment glint regardless of actual enchantments.

FireResistant

  • Type: Boolean
  • Required: No
  • Default: false
  • Description: Makes the item immune to fire/lava.

MaxStackSize

  • Type: Integer
  • Required: No
  • Default: Material default
  • Description: Overrides the maximum stack size.

MaxDamage

  • Type: Integer
  • Required: No
  • Default: Material default
  • Description: Sets the maximum durability. Must be ≥ 0.

Rarity

  • Type: String
  • Required: No
  • Values: Enum ItemRarity, e.g., COMMON, UNCOMMON, RARE, EPIC
  • Description: Rarity indicator in lore.

TooltipStyle

  • Type: String
  • Required: No
  • Format: <namespace>:<path>
  • Description: Custom style key for advanced tooltip formatting.

Equippable

  • Type: Section

  • Required: No

  • Fields:

    • EquipmentSlot (String)
    • CameraOverlay (String, <namespace>:<path>, optional)
    • EquipSound (String, <namespace>:<path>, optional)
    • AssetId (String, <namespace>:<path>, optional)
    • AllowedEntities (String, tag key, optional)
    • DamageOnHurt (Boolean)
    • Dispensable (Boolean)
    • Swappable (Boolean)

  • Description: Defines entity equipment behavior.

Glider

  • Type: Boolean
  • Required: No
  • Description: Grants gliding capability (elytra-like).

Consumable

  • Type: Section

  • Required: No

  • Fields:

    • ConsumeSeconds (Float)
    • HasConsumeParticles (Boolean)
    • Animation (String, enum ItemUseAnimation)

  • Description: Makes the item consumable.

Tool

  • Type: Section

  • Required: No

  • Fields:

    • DamagePerBlock (Integer)
    • DefaultMiningSpeed (Float)
    • Rules (Section):- custom Blocks tags, Speed (Float), CorrectForDrops (Boolean)

  • Description: Configures tool behavior, mining speeds, and block-specific rules.

Food

  • Type: Section

  • Required: No

  • Fields:

    • Nutrition (Integer)
    • Saturation (Float)
    • CanAlwaysEat (Boolean)

  • Description: Sets food properties when consumed.

DisplayName

  • Type: String
  • Required: No
  • Description: Sets the item’s display name, supports standard '&' color codes.

Lore

  • Type: List<String>
  • Required: No
  • Description: Adds description lines to the item, supports standard '&' color and format codes (e.g., &o&7A legendary sword).

Unbreakable

  • Type: Boolean
  • Required: No
  • Default: false
  • Description: Makes the item unbreakable.

Color

  • Type: String
  • Required: No
  • Format: any CSS-style color (e.g., #RRGGBB)
  • Description: Applies a color to leather armor or full-color items.

Enchantments

  • Type: List<String>
  • Required: No
  • Description: List of enchantments, format ENCHANTMENT_NAME:LEVEL.

Attributes

  • Type: Section
  • Required: No
  • Subfields: dynamic attribute keys, each with Amount, Operation, optional EquipmentSlotGroup
  • Description: Adds attribute modifiers (e.g., attack damage, speed).

ItemFlags

  • Type: List<String>
  • Required: No
  • Description: Hides default item flags via Bukkit ItemFlag name.

Example Configuration

Material: "DIAMOND_SWORD"
Amount: 1
RepairCost: 10
Rarity: "EPIC"
ItemName: "&6Excalibur"
Lore:
  - "&o&7A legendary sword"
  - "&l&4Unmatched in power"
Enchantments:
  - "DAMAGE_ALL:5"
  - "LOOT_BONUS_MOBS:3"
Consumable:
  ConsumeSeconds: 1.5
  HasConsumeParticles: true
  Animation: "EAT"
Attributes:
  ATTACK_SPEED:
    Amount: 1.2
    Operation: ADDITION
  MAX_HEALTH:
    Amount: 4.0
    Operation: MULTIPLY_BASE

Getting Started

Assets Configuration

Inventories

Developer API

Clone this wiki locally