Skip to content

module custom_items

Jump to bottom
goflishMC edited this page Apr 23, 2025 · 4 revisions

🛠️ custom_items Module

The custom_items module allows you to define static, custom Minecraft items with names, lore, enchantments, model data, unbreakability, flags, and color. These are typically used for crafting materials, collectibles, or cosmetic gear.

📁 File Structure

All custom item definitions are placed in:

/plugins/Divinity/modules/custom_items/items/

Each .yml file defines a single item. The file name becomes the internal item ID.

📦 Example Item File

name: '&5Adamantine Ingot'
lore:
  - '&8--------------------'
  - ' &7Refined adamantine used for crafting'
  - ' &7the most durable and powerful items.'
  - '&8--------------------'
material: PAPER
model-data: 29
color: -1,-1,-1
unbreakable: true
item-flags:
  - HIDE_ADDITIONAL_TOOLTIP
  - HIDE_ARMOR_TRIM
  - HIDE_ATTRIBUTES
  - HIDE_DESTROYS
  - HIDE_DYE
  - HIDE_ENCHANTS
  - HIDE_PLACED_ON
  - HIDE_UNBREAKABLE
enchantments: [ ]
tier: veryraremetals

🔍 Supported Fields

Field Description
name Display name (supports color codes).
lore Lore lines shown on the item.
material Bukkit material name (e.g. IRON_INGOT, DIAMOND_SWORD).
model-data Custom model data for resource pack support.
color RGB triplet for dyeable items. Use -1,-1,-1 to disable.
unbreakable Whether the item is unbreakable.
item-flags Controls hidden item attributes. See list below.
enchantments Map of enchantments (empty list if none).
tier Optional classification for use with other modules (e.g., socketing).

🧾 item-flags Reference

You can use any combination of the following flags to hide item metadata or visual indicators:

  • HIDE_ATTRIBUTES
  • HIDE_ENCHANTS
  • HIDE_UNBREAKABLE
  • HIDE_DESTROYS
  • HIDE_PLACED_ON
  • HIDE_DYE
  • HIDE_ARMOR_TRIM
  • HIDE_ADDITIONAL_TOOLTIP
  • '*' — hide all applicable flags

For a full list and explanation of available flags, see the official Spigot documentation:
🔗 Spigot ItemFlag Enum Reference

⚙️ Module Settings

File: /plugins/Divinity/modules/custom_items/settings.yml

command-aliases: customitems
item-format:
  name: '%ITEM_NAME%'
  lore:
    - '%ITEM_LORE%'
Setting Description
command-aliases Alternate command names for item retrieval.
item-format Placeholder formatting when generating item dynamically.

🎁 Giving Items Through Loot

Custom items can be given as rewards using the loot module:

rewards:
  - type: CUSTOM_ITEM
    id: adamantine_ingot
    amount: 1
    chance: 100.0
Field Description
type Must be CUSTOM_ITEM
id The YAML filename without .yml
amount Quantity to drop
chance Drop chance in percent

🧪 Usage Tips

  • Use model-data and resource packs to visually distinguish rare items.
  • Use tier to categorize crafting materials for use in other modules like fortify, socketing, or item_generator.
  • Combine with loot tables, vendor GUIs, or MythicMobs drops for advanced acquisition.

🧷 Command

Give yourself a custom item with:

/customitems get adamantine_ingot

Where adamantine_ingot.yml is the file name in the items/ folder.

Let me know when you’re ready to document item_generator or other modules that consume these item definitions!

Clone this wiki locally