Home

zMItemsBuilder Wiki

Custom items, kits, and scalable progression for Paper/Spigot servers.

Requires: Paper/Spigot 1.20+, Java 17+ Optional dependency: PlaceholderAPI

1. Overview

zMItemsBuilder lets you create fully custom items — weapons, armor sets, tools, consumables, keys, currency — directly from configuration files or in-game GUIs. Items can have:

Custom names, lore, and textures
Enchantments and attributes that scale with a "level"
Click actions (commands, sounds)
Usage limits and cooldowns
Passive potion effects while equipped
Restrictions like "cannot be crafted" or "cannot be dropped"

Everything is loaded on startup and can be reloaded live with /zmitems reload.

2. Installation and Files

Drop the .jar into your plugins/ folder.
Restart the server.
The following files are generated automatically:

File	Purpose
`config.yml`	General plugin settings
`items.yml`	Item, group, rarity, and template definitions
`data.yml`	Live data: effects, actions, cooldowns, uses
`saved_items.yml`	Manually saved item snapshots
`lang/lang_EN.yml`	English messages
`lang/lang_ES.yml`	Spanish messages

3. Creating Your First Item

This is the part most people ask about first, so read it before anything else. There are two ways to create an item. Pick whichever feels easier.

Method A — In-Game GUI (recommended for beginners)

Run:
```
/zmitems create my_sword
```
A menu opens asking you to pick a mode:
- Single — one item (sword, tool, potion, custom object)
- Armor — a full set (helmet, chestplate, leggings, boots)
- Tools — a tool set (axe, hoe, shovel, pickaxe)
Pick one. The plugin instantly writes a working template into items.yml under the name you chose (my_sword in this example), with a default material and default enchantments already set.
The item is now in your hand. Customize it using commands, for example:
```
/zmitems rename &bMy Sword
/zmitems lore add "&7A blade forged for testing."
/zmitems enchant sharpness 5
/zmitems glow
/zmitems unbreakable
```
Every one of these commands edits the item currently in your hand and saves the change back into items.yml automatically.
Give it to players any time with:
```
/zmitems give NORMAL <player> my_sword
```

That's it — no manual file editing required.

Method B — Editing items.yml Directly (advanced)

If you prefer working in the config file, open items.yml and add a new entry under items:. Every item needs at minimum a mode and a material:

items:
  my_sword:
    mode: single
    material: DIAMOND_SWORD
    name: "&bMy Sword"
    lore:
      - "&7A blade forged for testing."
    enchants:
      sharpness: 5
      unbreaking: 3

Then apply your changes:

/zmitems reload
/zmitems give NORMAL <player> my_sword

/zmitems reload re-reads the file, so any item you add or edit by hand becomes available immediately without restarting the server.

Which Method Should I Use?

Situation	Use
You just want a working item fast	Method A (GUI)
You want fine control over every field, or you're adding many items at once	Method B (manual YAML)
You already have an item and want to tweak one thing (name, one enchant, a flag)	Method A commands work on any existing item, not just newly created ones

Once your item exists, everything else in this wiki (attributes, progression, potion effects, click actions) is added on top of it, using the same two approaches: either a command, or a field in items.yml.

4. config.yml

config-version: 3
settings:
  language: EN
  use-roman-numerals: false
  secondary-color-mode: LIGHTER
  use-rarity: true
  sound:
    enabled: true
    type: ENTITY_EXPERIENCE_ORB_PICKUP
    volume: 1.0
    pitch: 1.0
update-check:
  enabled: true

Setting	What it does
`language`	`EN` or `ES` — controls plugin messages
`use-roman-numerals`	Shows enchant/kit levels as `I, II, III` instead of `1, 2, 3`
`secondary-color-mode`	How the lore's secondary color is derived: `LIGHTER`, `DARKER`, or `COMPLEMENTARY`
`use-rarity`	Enables the `{rarity}` placeholder in lore
`sound.*`	Sound played when a player receives a group/kit
`update-check.enabled`	Checks for plugin updates in the background

5. Commands

Base command: /zmitems (aliases: zmitems, zmib). Running it with no arguments opens the Help GUI.

Item Creation & Editing

Command	Description
`/zmitems create <name>`	Opens a GUI to create a new item (Single, Armor, or Tools)
`/zmitems clone <name> [group]`	Clones the item in your hand into `items.yml`
`/zmitems material <material>`	Changes the material of the item in hand
`/zmitems rename <name>`	Renames the item in hand (also `/rename`, `/irename`)
`/zmitems glow`	Toggles the enchant-glow visual effect
`/zmitems unbreakable`	Toggles unbreakable status
`/zmitems hide <flag>`	Toggles a Bukkit `ItemFlag` (e.g. `HIDE_ENCHANTS`)
`/zmitems armor_trim <material> <pattern>` / `remove`	Applies or removes an armor trim
`/zmitems info`	Shows material, item ID, and custom model data of the held item

Lore & Enchantments

Command	Description
`/zmitems lore add <text>`	Adds a lore line
`/zmitems lore remove <line#>`	Removes a lore line
`/zmitems lore set <line#> <text>`	Replaces a lore line
`/zmitems lore reset`	Clears all lore
`/zmitems lore copy` / `paste`	Copies/pastes lore between items
`/zmitems enchant <name> <level>`	Adds an enchant (level `0` removes it)

Supports & color codes, &#RRGGBB hex, and MiniMessage.

Distribution

Command	Description
`/zmitems give NORMAL <player> <id> [amount] [prefix]`	Gives one item
`/zmitems give GROUP <player> <groupId> [prefix]`	Gives every item in a group
`/zmitems item save <name>`	Saves the held item to `saved_items.yml`
`/zmitems item show`	Opens a paginated GUI of saved items
`/zmitems item give <player> <name> <amount> [notify]`	Gives a saved item
`/zmitems item remove <name>`	Deletes a saved item
`/zmitems item update <name>`	Overwrites a saved item with the one in hand

Attributes, Effects & Actions

Command	Description
`/zmitems attribute add hand <attr> <value> <op> <slot>`	Adds an attribute to the held item
`/zmitems attribute add item <item> <attr> <value> <op> <slot>`	Adds an attribute to a config item
`/zmitems attribute remove <attr> hand` / `item <item>`	Removes an attribute
`/zmitems effect add <id> <effect> [duration] [amplifier] [slot]`	Adds a passive potion effect
`/zmitems effect remove <id> <effect>`	Removes a passive effect
`/zmitems effect list <id>`	Lists effects on an item
`/zmitems action add <id> <type> [click] <value>`	Adds a click action (see section 10)
`/zmitems action remove <id>`	Opens a GUI to remove actions

Restrictions & Progression

Command	Description
`/zmitems flag [flag]`	Toggles a behavior flag, or opens the Flags GUI with no argument
`/zmitems progression [enchant\|attribute] [item]`	Opens the progression editor GUI

Administration

Command	Description
`/zmitems reload`	Reloads all configuration files
`/zmitems migrate`	Opens a GUI to migrate legacy items to the current identity system

6. Permissions

Permission	Default	Grants
`zmitemsbuilder.use`	true	Access to `/zmitems`
`zmitemsbuilder.info`	true	View held item info
`zmitemsbuilder.create`	op	Create items via GUI
`zmitemsbuilder.give`	op	Give items to players
`zmitemsbuilder.reload`	op	Reload the plugin
`zmitemsbuilder.material`	op	Change held item's material
`zmitemsbuilder.lore`	op	Edit lore
`zmitemsbuilder.enchant`	op	Edit enchantments
`zmitemsbuilder.rename`	op	Rename items
`zmitemsbuilder.glow`	op	Toggle glow
`zmitemsbuilder.hide`	op	Toggle Bukkit item flags
`zmitemsbuilder.flag`	op	Toggle behavior flags
`zmitemsbuilder.unbreakable`	op	Toggle unbreakable
`zmitemsbuilder.armortrim`	op	Apply/remove armor trims
`zmitemsbuilder.clone`	op	Clone held item into config
`zmitemsbuilder.progression`	op	Configure progression rules
`zmitemsbuilder.attribute`	op	Manage attributes
`zmitemsbuilder.action`	op	Manage click actions
`zmitemsbuilder.effect`	op	Manage potion effects
`zmitemsbuilder.item`	op	Manage saved items
`zmitemsbuilder.migrate`	op	Migrate legacy items

Legacy fallback permissions: zmkits.give, zmkits.create, zmkits.reload are also accepted.

7. Item Fields Reference (items.yml)

Item Modes

Mode	Produces
`single`	One item (sword, head, potion, custom item, etc.)
`armor`	A full armor set — `helmet`, `chestplate`, `leggings`, `boots`
`tools`	A tool set — any of `axe`, `hoe`, `shovel`, `pickaxe`

Core Fields

Field	Description
`material`	Bukkit material name (or `base-material` for armor/tools, e.g. `NETHERITE`)
`pieces`	Which pieces to generate for `armor`/`tools` mode
`name`	Display name template (supports placeholders and color codes)
`display-type`	Friendly label used by the `{item_type}` placeholder
`lore`	List of lore lines (supports placeholders)
`id_item`	Public ID used to attach effects, actions, and cooldowns in `data.yml`
`amount`	Stack size given (default `1`)
`unbreakable`	`true`/`false`
`glow`	Adds the enchant shimmer without showing an enchantment
`custom-model-data`	Custom model data value for resource packs
`enchants`	Fixed values or progression rules (section 8)
`attributes`	Stat bonuses (armor, health, speed, etc.)
`potion-effects`	Effects applied on consumption (for consumables)
`item-flags`	Bukkit `ItemFlag`s, e.g. `HIDE_ATTRIBUTES`, `HIDE_ENCHANTS`
`behavior-flags`	Plugin restrictions — section 11
`head-texture` / `base64`	Player head skin (from `heads-texture` section or a raw base64 string)

Example — Armor Set

items:
  special_armor:
    mode: armor
    material: NETHERITE
    pieces: [helmet, chestplate, leggings, boots]
    enchants:
      protection: 10
      unbreaking: 5
      mending: 5
    attributes:
      max_health:
        attribute: MAX_HEALTH
        amount: 10.0
        operation: ADD_NUMBER
        slot: ALL

Example — Consumable with Potion Effects

items:
  special_elixir:
    mode: single
    material: POTION
    glow: true
    potion-effects:
      regen:
        type: REGENERATION
        duration: 10
        amplifier: 2
      absorp:
        type: ABSORPTION
        duration: 120
        amplifier: 1

Player Head Items

heads-texture:
  special: "eyJ0ZXh0dXJlcyI6..."

items:
  special_head:
    mode: single
    material: PLAYER_HEAD
    head: special

Currency & Key Items

Simple, non-equippable items (keys, coins, tokens) just need material, display-type, id_item, and restrictive behavior-flags:

items:
  special_coin:
    mode: single
    material: REDSTONE_BLOCK
    display-type: "Coin"
    id_item: "coin_special"
    amount: 16
    glow: true
    behavior-flags:
      - NO_PLACE
      - NO_CRAFT

Aesthetic Templates

The esthetic section defines reusable name/lore formatting shared by every item that doesn't override it:

esthetic:
  name-template: "&f{item_type} &8▸ {prefix_item}"
  enchant-format: "   {primary_color}• &f{enchant_name} {secondary_color}{level}"
  lore-template:
    - "&7"
    - " {primary_color}Enchantments:"
    - "{enchants}"
    - " {primary_color}Rarity: {primary_color}{rarity}"

Rarities

Purely cosmetic labels referenced by {rarity}:

raritys:
  special: "★★★&7★★"
  objects: "★★★★&7★"
  levels: ""

8. Progression System

Progression lets enchantment levels, attribute values, and potion effects scale automatically with an item's level (set on its group — see section 9).

Enchantments — Four Ways to Define a Value

1. Fixed value

enchants:
  sharpness: 5

2. Per level — base + (level - 1) × per-level

enchants:
  protection:
    base: 4
    per-level: 1
    max: 10

3. Interval — base + floor((level - 1) / every) × bonus

enchants:
  fire_protection:
    base: 1
    every: 3
    bonus: 1
    max: 4

4. Math expression — full control using level as a variable

enchants:
  efficiency: "1 + level * 2"

Supports + - * / %, functions min(), max(), floor(), ceil(), round(), and parentheses.

Attributes with Progression

attributes:
  max_health:
    attribute: MAX_HEALTH
    amount:
      base: 10.0
      per-level: 2.0
      max: 30.0
    operation: ADD_NUMBER
    slot: HELMET

Operations: ADD_NUMBER, ADD_SCALAR, MULTIPLY_SCALAR_1, ADD_PERCENTAGE (alias of ADD_SCALAR) Slots: MAIN_HAND, OFF_HAND, HAND, HELMET, CHESTPLATE, LEGGINGS, BOOTS, ANY, ALL

Potion Effects with Progression

duration and amplifier accept the same fixed/per-level/interval formats:

potion-effects:
  regen:
    type: REGENERATION
    duration: 10
    amplifier: 2

In-Game Editor

Run /zmitems progression to configure any of the above through a guided GUI instead of editing YAML by hand.

9. Groups (Kits)

Groups bundle multiple items together, assign them a shared rarity and level, and let you give them all at once.

groups:
  special:
    rarity: special
    items:
      - special_sword
      - special_armor
      - special_pickaxe

  level_1:
    rarity: levels
    level: 1
    items:
      - levels_set

level feeds every progression rule inside the group's items.
Give an entire group with /zmitems give GROUP <player> <groupId>.

10. data.yml: Effects, Actions and Cooldowns

While items.yml defines what an item looks like, data.yml defines what it does. It is keyed by id_item, and is normally edited through commands rather than by hand.

Passive Effects (while equipped)

Applies continuously as long as the item stays in the given slot (checked every 4 seconds):

items:
  offhand_speed:
    effects:
      speed:
        type: SPEED
        duration: 200
        amplifier: 1
        slot: OFF_HAND

Command equivalent: /zmitems effect add offhand_speed SPEED 10s 2 OFF_HAND

Click Actions, Cooldown & Uses

Example — a consumable apple that grants buffs on right-click, with a cooldown and limited uses:

items:
  addam_apple:
    cooldown: 5
    uses: 3
    actions:
      '0':
        type: sound
        value: BLOCK_LAVA_POP
        click: RIGHT_CLICK
      '1':
        type: console_command
        value: "minecraft:effect give %player% minecraft:speed 30 1"
        click: RIGHT_CLICK
      '2':
        type: console_command
        value: "minecraft:effect give %player% minecraft:strength 30 1"
        click: RIGHT_CLICK
      '3':
        type: console_command
        value: "minecraft:effect give %player% minecraft:fire_resistance 60 1"
        click: RIGHT_CLICK

Built with these commands:

/zmitems action add addam_apple sound RIGHT_CLICK BLOCK_LAVA_POP
/zmitems action add addam_apple console_command RIGHT_CLICK minecraft:effect give %player% minecraft:speed 30 1
/zmitems action add addam_apple cooldown 5
/zmitems action add addam_apple uses 3

Action Types

Type	Description
`player_command`	Runs a command as the player
`console_command`	Runs a command from console
`sound`	Plays a sound, optionally `NAME:volume:pitch`

Click types: RIGHT_CLICK, LEFT_CLICK, SHIFT_RIGHT_CLICK, SHIFT_LEFT_CLICK

Cooldowns & Uses

Concept	Behavior
`cooldown`	Seconds between uses, tracked per player in memory (resets on restart)
`uses`	Max uses per stack, stored on the item itself; item is consumed at 0

11. Behavior Flags

Restrict what players can do with an item. Stored directly on the item.

Flag	Blocks
`NO_PLACE`	Placing as a block
`NO_CRAFT`	Use in crafting recipes
`NO_DROP`	Dropping the item
`NO_USE`	Right-click interaction
`NO_CONSUME`	Eating/drinking
`NO_EQUIP`	Equipping as armor
`NO_ANVIL`	Anvil use
`NO_SMITHING`	Smithing table use
`NO_GRINDSTONE`	Grindstone (disenchanting)
`NO_ENCHANT`	Enchanting table use
`NO_BREWING`	Brewing stand use
`NO_FURNACE`	Furnace/blast furnace/smoker use

Each flag also accepts common aliases (e.g. NO_DROP also matches DROP, BLOCK_DROP, CANNOT_DROP).

Apply with /zmitems flag <FLAG>, or open the visual toggle menu with /zmitems flag.

12. Placeholders

Name & Lore

Placeholder	Description
`{item_type}`	From `display-type`, or the material name
`{prefix_item}`	Prefix text passed when giving the item
`{level}`	The group's level
`{rarity}`	Rarity label from the `raritys` section
`{enchants}`	Auto-generated enchantment lines
`{primary_color}` / `{secondary_color}`	Colors derived from the name gradient
`{gradient:text}`	Renders text using the primary/secondary gradient
`{attribute_level:<name>}`	Resolved value of an attribute at the group's level

Click Actions

Placeholder	Description
`%player%`	Player name
`%displayname%`	Player display name
`%world%`	Current world
`%x%` `%y%` `%z%`	Player coordinates

If PlaceholderAPI is installed, all PAPI placeholders (%papi_...%) also work.

13. Item Identity System

Every item produced by the plugin carries two hidden tags:

Tag	Written when	Used for
`source_key`	Always	Locating the item back in `items.yml`
`item_id`	Only if `id_item:` is set	Linking to effects/actions/cooldowns in `data.yml`

Older items that only have item_id still work — the plugin resolves them automatically. Run /zmitems migrate to backfill source_key on legacy items.

14. Languages

Two languages are bundled: EN and ES. Switch with settings.language in config.yml. Messages support & color codes, &#RRGGBB hex, and MiniMessage tags (<gradient>, <bold>, <click>, <hover>).

15. Security Notes

Config files (items.yml, data.yml) are written atomically to prevent corruption on crash.
Cooldowns and in-progress editor sessions live in memory and reset on server restart.
%displayname% in actions is not sanitized — a malicious display name could inject extra command text. Avoid using %displayname% in console_command actions on servers with untrusted name sources.

zMItemsBuilder

Home

Getting Started

Configuration

Building Items

Item Behavior

Reference

Templates

Home

zMItemsBuilder Wiki

Table of Contents

1. Overview

2. Installation and Files

3. Creating Your First Item

Method A — In-Game GUI (recommended for beginners)

Method B — Editing items.yml Directly (advanced)

Which Method Should I Use?

4. config.yml

5. Commands

Item Creation & Editing

Lore & Enchantments

Distribution

Attributes, Effects & Actions

Restrictions & Progression

Administration

6. Permissions

7. Item Fields Reference (items.yml)

Item Modes

Core Fields

Example — Armor Set

Example — Consumable with Potion Effects

Player Head Items

Currency & Key Items

Aesthetic Templates

Rarities

8. Progression System

Enchantments — Four Ways to Define a Value

Attributes with Progression

Potion Effects with Progression

In-Game Editor

9. Groups (Kits)

10. data.yml: Effects, Actions and Cooldowns

Passive Effects (while equipped)

Click Actions, Cooldown & Uses

Action Types

Cooldowns & Uses

11. Behavior Flags

12. Placeholders

Name & Lore

Click Actions

13. Item Identity System

14. Languages

15. Security Notes

Uh oh!

Uh oh!

Clone this wiki locally