Creating Items

Creating Items

Learn how to create custom items with zItems, from simple sticks to complex tools with effects, metadata, and recipes.

Quick Start

Your First Item

Create a file items/my_stick.yml:

id: "my_stick"
material: STICK
display-name: "<aqua>My Custom Stick</aqua>"
lore:
  - "<gray>My first custom item!"

Reload and test:

/zitems reload
/zitems item give <player-name> my_stick

That's it! You've created your first custom item.

File Structure

Items Directory

All item files go in plugins/zItems/items/:

Subdirectories are supported - organize items however you like!

File Naming

  • Use snake_case: hammer_pickaxe.yml ✅

  • Avoid spaces: hammer pickaxe.yml ❌

  • Be descriptive: tool1.yml vs farming_hoe.yml ✅

Basic Configuration

Required Fields

Every item needs these fields:

id

Unique identifier for this item.

Rules:

  • Must be unique across all items

  • Use snake_case

  • Only letters, numbers, underscore

  • No spaces

Examples:

material

Bukkit Material enum value.

Examples:

Find materials: Bukkit Materials

display-name

Item name shown to players, using MiniMessage format.

Examples:

MiniMessage docs: Adventure MiniMessage

Optional Fields

lore

List of lore lines displayed under the item name.

Tips:

  • Use "" for empty lines

  • Keep lines short (< 40 characters)

  • Use colors for organization

custom-model-data

Custom model data value for resource packs.

Use case: Custom textures/models via resource pack.

max-stack-size

Maximum stack size (1-99).

max-damage

Maximum durability (for tools/weapons).

Note: Requires unbreakable: false.

unbreakable

Make item unbreakable (infinite durability).

hide-tooltip

Hide all tooltip information (enchants, attributes, etc.).

trackable

Enable block tracking (for custom blocks).

Use case: Custom blocks that should drop the custom item when broken.

See: Block Tracking

Enchantments

Add vanilla enchantments to items:

Format

Enchantment types: Bukkit Enchantment

Examples

Attributes

Add vanilla attributes (armor, attack damage, etc.):

Format

Attribute types:

  • armor - Armor points

  • armor_toughness - Armor toughness

  • attack_damage - Attack damage

  • attack_speed - Attack speed

  • knockback_resistance - Knockback resistance

  • max_health - Max health

  • movement_speed - Movement speed

  • luck - Luck

Operations:

  • ADD_NUMBER - Add amount (e.g., +10 armor)

  • ADD_SCALAR - Add percentage (e.g., +50% = 0.5)

  • MULTIPLY_SCALAR_1 - Multiply by (1 + amount)

Slots (optional):

  • HAND, OFF_HAND

  • HEAD, CHEST, LEGS, FEET

Attribute Merge Strategy

Control how custom attributes merge with default item attributes:

Strategies:

  • REPLACE - Replace all existing attributes (default)

  • ADD - Keep existing + add new (may create duplicates)

  • KEEP_HIGHEST - Keep highest value for each attribute

  • KEEP_LOWEST - Keep lowest value for each attribute

  • SUM - Sum values for each attribute

Example:

Examples

Effects

Apply custom effects to items:

Effects are effect IDs defined in effects/ directory.

See: Effects System

Effect Display Control

Control how effects appear in lore:

See: Effect Lore Display

Metadata System

Add special functionality using metadata:

Available metadata types:

  • food - Food properties

  • potion - Potion effects and color

  • leather-armor - Leather armor color

  • trim - Armor trims

  • banner - Banner patterns

  • enchant-storage - Stored enchantments (for books)

See: Metadata System

Recipes

Add crafting recipes for your items:

Recipe Types

Shaped Crafting

Pattern:

  • 3x3 grid

  • Use any character for ingredients

  • Space = empty slot

Shapeless Crafting

Order doesn't matter - just put ingredients anywhere.

Smelting

Smithing

Ingredient Types

Common tags:

  • logs - All log types

  • planks - All plank types

  • stone_tool_materials - Cobblestone, blackstone, etc.

  • wooden_slabs - All wooden slabs

Recipe Examples

Complete Examples

Simple Stick

Hammer Pickaxe

Auto-Sell Pickaxe with Recipe

Golden Apple with Food Metadata

Trimmed Netherite Armor

Hidden Additional Effects

Usage:

Advanced Topics

Custom Model Data

Use resource packs for custom textures:

How it works:

  1. Create resource pack with custom model

  2. Assign model to custom model data value

  3. Set value in item YAML

  4. Item displays with custom texture

Resource pack tutorial: Minecraft Model Guide

Trackable Blocks

For custom blocks that should drop the custom item:

How it works:

  1. Player places ruby_ore item as a block

  2. BlockTracker remembers: "This block is ruby_ore"

  3. Player breaks it (or uses Hammer/Vein Mining)

  4. Drops ruby_ore item instead of STONE

See: Block Tracking

Effect Restrictions

Control which effects can be added:

Use case: Prevent overpowered combinations.

Testing Your Items

Step 1: Create Item File

items/my_pickaxe.yml:

Step 2: Reload

Check console:

Step 3: Give Item

Or:

Step 4: Test

  • Check display name

  • Check lore

  • Test enchantments

  • Test effects

  • Test recipe (if applicable)

Step 5: Iterate

Edit YAML → /zitems reload → Test again

Common Issues

Item not loading

Symptoms:

  • /zitems item give says "Item not found"

  • Console shows no "Registered item: X"

Checklist:

  1. Is file in plugins/zItems/items/ (or subdirectory)?

  2. Is file named .yml?

  3. Are required fields present (id, material, display-name)?

  4. Is YAML syntax valid? (Check for indentation errors)

Debug:

YAML syntax error

Error:

Common causes:

  • Inconsistent indentation (use spaces, not tabs)

  • Missing quotes around special characters

  • Unclosed strings

Example fix:

Recipe not working

Symptoms:

  • Crafting doesn't work

  • Recipe not shown in recipe book

Checklist:

  1. Is recipe: block present?

  2. Is type valid? (CRAFTING_SHAPED, CRAFTING_SHAPELESS, etc.)

  3. Do ingredient materials exist?

  4. For shaped: Is pattern valid? (Max 3x3)

Debug: Enable debug mode and check:

Effects not applying

Symptoms:

  • Item has effects in config

  • Effects don't work in-game

Checklist:

  1. Do effect files exist in effects/?

  2. Are effect IDs correct?

  3. Does effect's can-apply-to allow this material?

Test:

If this works, the effect is fine. Check item config.

Best Practices

  1. Use descriptive IDs - hammer_pickaxe not item1

  2. Organize with subdirectories - tools/, weapons/, armor/

  3. Keep lore concise - Max 3-5 lines

  4. Test after changes - /zitems reload is fast!

  5. Use MiniMessage formatting - More powerful than legacy codes

  6. Document complex items - Add comments in YAML

  7. Balance effects - Don't make items too overpowered

  8. Use recipes - Make items craftable for survival

  9. Consistent naming - Use a naming convention and stick to it

  10. Version control - Use git for your items directory!

Next Steps

Now that you can create items:

  1. Effects System - Add powerful effects to items

  2. Effect Handlers Reference - All available effects

  3. Metadata System - Food, potions, trims, etc.

  4. Effect Lore Display - Customize effect display

Need help? Join our Discord or check GitHub Issues!

PreviousConfigurationNextEffects System

Last updated