search

Creating Items

hashtag
Creating Items

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

hashtag
Quick Start

hashtag
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.

hashtag
File Structure

hashtag
Items Directory

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

Subdirectories are supported - organize items however you like!

hashtag
File Naming

  • Use snake_case: hammer_pickaxe.yml ✅

  • Avoid spaces: hammer pickaxe.yml ❌

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

hashtag
Basic Configuration

hashtag
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 Materialsarrow-up-right

display-name

Item name shown to players, using MiniMessage format.

Examples:

MiniMessage docs: Adventure MiniMessagearrow-up-right

hashtag
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

hashtag
Enchantments

Add vanilla enchantments to items:

hashtag
Format

Enchantment types: Bukkit Enchantmentarrow-up-right

hashtag
Examples

hashtag
Attributes

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

hashtag
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

hashtag
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:

hashtag
Examples

hashtag
Effects

Apply custom effects to items:

Effects are effect IDs defined in effects/ directory.

See: Effects System

hashtag
Effect Display Control

Control how effects appear in lore:

See: Effect Lore Display

hashtag
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

hashtag
Recipes

Add crafting recipes for your items:

hashtag
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

hashtag
Ingredient Types

Common tags:

  • logs - All log types

  • planks - All plank types

  • stone_tool_materials - Cobblestone, blackstone, etc.

  • wooden_slabs - All wooden slabs

hashtag
Recipe Examples

hashtag
Complete Examples

hashtag
Simple Stick

hashtag
Hammer Pickaxe

hashtag
Auto-Sell Pickaxe with Recipe

hashtag
Golden Apple with Food Metadata

hashtag
Trimmed Netherite Armor

hashtag
Hidden Additional Effects

Usage:

hashtag
Advanced Topics

hashtag
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 Guidearrow-up-right

hashtag
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

hashtag
Effect Restrictions

Control which effects can be added:

Use case: Prevent overpowered combinations.

hashtag
Testing Your Items

hashtag
Step 1: Create Item File

items/my_pickaxe.yml:

hashtag
Step 2: Reload

Check console:

hashtag
Step 3: Give Item

Or:

hashtag
Step 4: Test

  • Check display name

  • Check lore

  • Test enchantments

  • Test effects

  • Test recipe (if applicable)

hashtag
Step 5: Iterate

Edit YAML → /zitems reload → Test again

hashtag
Common Issues

hashtag
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:

hashtag
YAML syntax error

Error:

Common causes:

  • Inconsistent indentation (use spaces, not tabs)

  • Missing quotes around special characters

  • Unclosed strings

Example fix:

hashtag
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:

hashtag
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.

hashtag
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!

hashtag
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 Discordarrow-up-right or check GitHub Issuesarrow-up-right!

PreviousConfigurationNextEffects System

Last updated