Introduction

Quick Start Guide

Get started with zItems in 5 minutes! This guide will walk you through creating your first custom item with effects.

Prerequisites

Before starting, ensure you have:

  • ✅ zItems installed and running

  • ✅ zMenu plugin installed

  • ✅ Server running Paper/Spigot 1.21+

If you haven't installed zItems yet, see the Installation Guide.

Step 1: Understanding the File Structure

After installation, zItems creates this structure:

plugins/zItems/
├── config.yml          # Plugin settings
├── messages.yml        # Customizable messages
├── items/              # Your custom items go here
└── effects/            # Your effect definitions go here

Key Concept:

  • Effects are reusable abilities (like Hammer, Vein Mining)

  • Items are actual items that use those effects

Step 2: Create Your First Effect

Let's create a simple Hammer effect that mines in a 3x3 area.

Create: plugins/zItems/effects/my_hammer.yml

Save the file and reload:

You should see: §aItems plugin reloaded successfully.

Step 3: Create Your First Item

Now let's create a pickaxe that uses your hammer effect.

Create: plugins/zItems/items/super_pickaxe.yml

Save and reload:

Step 4: Get Your Item

Give yourself the item:

You should receive your Super Pickaxe with the Hammer effect!

Step 5: Test It Out

  1. Find some stone blocks

  2. Mine a block with your Super Pickaxe

  3. Watch it break a 3x3 area! ⚒️

What's happening:

  • The Hammer effect detects when you break a block

  • It finds all blocks in a 3x3x1 area

  • It breaks them all and collects the drops

  • Your pickaxe takes 1 durability damage per block

Step 6: View Effect Details

Want to see what effects are on your item?

This shows:

  • All effects on the item in your hand

  • Effect IDs and display names

  • Handler types and priorities

What's Next?

Add More Effects

Let's add Auto-Sell to automatically sell mined blocks!

Create: plugins/zItems/effects/auto_sell.yml

Update your pickaxe: plugins/zItems/items/super_pickaxe.yml

Reload and give yourself a new pickaxe - it now mines AND sells automatically!

Note: Requires a shop plugin (EconomyShopGUI, ShopGUIPlus, or ZShop).

Create an Effect Item (Smithing Table)

You can create items that represent effects and apply them in smithing tables!

Create: plugins/zItems/effects/hammer_stone.yml

Give yourself the stone:

Use it in a smithing table:

  1. Place Netherite Upgrade Template

  2. Place your pickaxe

  3. Place the Hammer Stone

  4. Take out your enhanced pickaxe!

Common Customizations

Change Effect Display

Control how effects appear on items:

Prevent Adding More Effects

Create Recipes

Add a crafting recipe:

Troubleshooting

Effect Not Working

Problem: "I added the effect but it's not working!"

Checklist:

  1. Did you reload after creating the effect? /zitems reload

  2. Is the effect ID spelled correctly in your item config?

  3. Check console for errors when loading effects

  4. Use /zitems effect view to confirm the effect is on the item

Item Not Showing Effect Lore

Problem: "The effect doesn't appear in the lore!"

Causes:

  1. nb-effects-view: 0 hides all effects

  2. base-effects-visible: false hides base effects

  3. Effect doesn't have a display-name set

Solution:

Can't Give Item

Problem: "/zitems item give doesn't work!"

Solutions:

  1. Check permission: items.command.item.give

  2. Check item ID spelling

  3. Check console for errors

  4. Try: /zitems item give <player_name> super_pickaxe 1

Example: Complete Mining Tool

Here's a complete example of a powerful mining tool:

Effect: plugins/zItems/effects/ultimate_mining.yml

Item: plugins/zItems/items/ultimate_pickaxe.yml

Next Steps

Now that you've created your first items, explore more:

  1. All Effect Types - Complete effect reference

  2. Creating Items - Advanced item configuration

  3. Effect Lore Control - Customize effect display

  4. Commands Reference - All available commands

Tips & Best Practices

Organize Your Files

Use Consistent Naming

Test Incrementally

  1. Create one effect

  2. Test it

  3. Create the item

  4. Test it

  5. Add more effects

Don't create everything at once - test as you go!

Use MiniMessage Format

Take advantage of MiniMessage formatting:

Learn more: MiniMessage Documentation

Congratulations! 🎉 You've created your first custom item with zItems!

Need help? Join our Discord or check GitHub Issues.

PreviousSUMMARYNextInstallation

Last updated