zCustomGear - Armor Sets & Talismans 2.8.1

zCustomGear
Custom armor sets, talismans and crates with rarity tiers and full-set bonuses
By @zArrowTan (Arrow Plugins). Formerly zArmorSets.

📋 Overview

zCustomGear lets you build custom armor sets and talismans in YAML, each with its own rarity tier and bonuses that activate when the full set is worn or the talisman is held. Define potion effects, attribute boosts, gameplay toggles, particles, and economy perks, then hand the gear out and let players chase the tiers.

Crates round it off: build your own loot boxes that hand out any of it, with the odds worked out for you. One jar, Minecraft 1.18 to 1.21.11+, zero required dependencies.

🛡 Armor Sets

• Define sets in YAML with fully configurable rarity tiers, from Common to Mythic
• Bonuses activate only when the configured set is worn, with an optional partial-bonus mode for wearing 2 or 3 pieces
• Pieces are matched via PersistentDataContainer tags, so they never collide with vanilla items
• Items from the creative menu or other plugins won't trigger sets, only properly tagged gear does

💫 Bonus Types

• Potion Effects: any effect, with hide-particles support
• Attribute Modifiers: max-health, attack-damage, and more
• Gameplay Toggles: no-hunger, glowing with team color, fire and fall immunity, unbreakable
• Particles: native Bukkit particles with color support on dust particles, configurable type, interval, offset, and count
• Smart Glow Color: resolves set-level, then rarity-level, then none, so a tier color is the default and any set can override it

🔖 Talismans

• Inventory-held trinkets that grant bonuses passively. Carry several at once and their bonuses all apply
• One per slot, never merging into a stack, so moving them around always behaves predictably
• Optional timer: a consumable countdown that ticks only while carried, pauses when stored, and destroys the item at zero
• Right-click activation gate: crate drops can be resold before the countdown ever starts
• No stray weapon stats. A talisman built on a sword or a tool hides its attack damage, attack speed and the vanilla item line, because a talisman is passive
• Talismans support the same bonus types and integrations as armor sets

🎒 Talisman Bag

Give players a dedicated bag to keep their talismans tidy. While the bag is anywhere in a player's inventory, every talisman inside still gives its bonus, just like carrying it in a normal slot, only neater.

• Easy to use: right-click the bag (or run /zcg bag while holding it) to open it, drag talismans in, and close. Bonuses turn on right away.
• Smart contents: accepts only normal talismans, and turns away timer talismans, armor, weapons, and other bags. Any wrong item is handed back when the bag closes, so nothing is ever lost.
• No duplicates: a bag will not take a talisman it already holds. On by default, and you can allow copies in the config.
• Live contents list: a lime bundle look by default that prints the talismans inside right on the item and updates while the bag is open, with Minecraft's built-in bundle text hidden for you.
• Instant either way: pull a talisman out of an open bag and its bonus stops the moment it leaves, screen still open.
• Configurable: set the size (1 to 6 rows), the material and model data for a custom texture, the contents header and empty text, whether duplicates are allowed, and whether the bag survives death.

📦 Crates

Build your own loot boxes. A crate is an item a player right-clicks to open, and a reward can be an item, one set piece, a full set, a talisman, a talisman bag, or a console command. Each crate is one file in crates/, exactly like sets and talismans, and a working example is created for you on first start.

• Two roll modes. weight always gives the number of rewards you set and weighs each one against the others. chance rolls every reward on its own percent, so one open can give several or none
• Guaranteed rewards are always given, in either mode
• The odds are printed for you. Turn on show-rewards-in-lore and the crate item lists its rewards with the percentages filled in, so the lore can never drift from what the crate actually does
• Nothing is lost to a full inventory. With require-empty-slot the open is refused and the player keeps the crate
• Per-crate control over rolls, unique rolls, keep-on-death, the open sound, and an optional permission to lock it

✨ Glow That Keeps the Rank Prefix

A glowing set does not touch a player's rank prefix or name colour, whether that comes from TAB, LuckPerms or Nametagedit. The original colour returns when the armour comes off, and the glow comes back on its own after a relogin or a respawn.

You choose what the set colour applies to. Minecraft uses one colour for both the glow outline and the name above the head, so recolor-nametag decides which one wins: the set colour on both, or the name keeping its rank colour with the glow following it.

Install PacketEvents for this. Without it the plugin still runs, but a rank prefix can disappear while a player is glowing.

🔄 Live Item Refresh & Instant Effects

• Edit a set or a talisman in YAML and run /zcg reload. Items players already hold rebuild their name, lore, model data and unbreakable flag in place from the current config, with no need to give them out again
• Enchantments are left untouched, so anvil work survives a refresh, and timer talismans keep their countdown
• Instant on and off: talisman and armor-set effects turn on while carried or worn and off the moment the item is removed, with no fade-out delay and no night-vision flicker
• Optional keep-on-death per set and per talisman, tagged items survive death and snap back to the correct slot on respawn

🔌 Integrations

All integrations are soft-depends. If the plugin isn't installed, zCustomGear just logs an info line and carries on.

• CoreJobs: per-set and per-talisman multipliers for job XP, job money and farmpoints, each with its own key. Needs CoreJobs 1.4.0 or newer
• EcoJobs: per-set and per-talisman XP multiplier
• EconomyShopGUI: sell multiplier applied across the shop GUI, quick-sell, sell-all, shopstands, and auto-sell chests
• ItemsAdder: use a custom item as the base (itemsadder: namespace:id), with the resource-pack texture preserved and a material fallback when missing
• PacketEvents: glow color survives rank and nametag plugins like TAB and LuckPerms-Prefix

The gear bonus is visible to players. zCustomGear reports what it is giving to CoreJobs, so %corejobs_total_xp_multiplier% shows the boost and the gear together, and %corejobs_external_xp_source% names zCustomGear as the source. A set and a talisman that both boost the same payout multiply together, and any boost the player already bought is stacked on rather than replaced.

💾 Storage

• SQLite by default (file-based) or MySQL via a HikariCP pool
• All database I/O runs off the main thread
• If MySQL fails to connect, the plugin falls back to SQLite automatically and logs a warning
• Configs auto-migrate on update, so new keys arrive without touching your edits

⚙ Defining a Set

Drop a file into plugins/zCustomGear/sets/<id>.yml. A fully annotated dragonlord.yml ships as a reference.

id: dragonlord
display-name: "&#ff6b6bDragonlord Set"
rarity: legendary
required-pieces: 4
activation-message: "&#ffd700You feel the power of the Dragonlord!"
pieces:
  helmet:     { material: NETHERITE_HELMET,     unbreakable: true, custom-model- 1001 }
  chestplate: { material: NETHERITE_CHESTPLATE, unbreakable: true, custom-model- 1002 }
  leggings:   { material: NETHERITE_LEGGINGS,   unbreakable: true, custom-model- 1003 }
  boots:      { material: NETHERITE_BOOTS,      unbreakable: true, custom-model- 1004 }
bonuses:
  potion-effects:
    - { type: STRENGTH, amplifier: 1, hide-particles: true }
  attributes:
    max-health: 4
    attack-damage: 2
  toggles:
    no-hunger: true
    glowing: true
    glow-color: RED
  particles:
    enabled: true
    type: FLAME
    color: "255,215,0"
    interval-ticks: 10
    offset: 0.5
    count: 5
  integrations:
    corejobs-xp-multiplier: 1.25
    economyshopgui-sell-multiplier: 1.15

⌨️ Commands

Base command /zcustomgear (aliases /zcg, /customgear).

• /zcg list
  List defined armor sets
• /zcg info <set>
  Show details for a set
• /zcg give <player> <set> [piece|all]
  Give a piece or full set to a player
• /zcg test [set]
  Equip a set on yourself for testing
• /zcg talisman <list|info <id>|give <player> <id>>
  Talisman management
• /zcg bag <give <player>>
  Give a talisman bag, or open your held bag with /zcg bag
• /zcg crate <list|info <id>|give <player> <id> <amount>>
  Crate management
• /zcg reload
  Reload all config and live-refresh tagged items

🔐 Permissions

• zcustomgear.admin (op)
  Full access
• zcustomgear.use (true)
  Receive bonuses
• zcustomgear.give (op)
  Use /zcg give
• zcustomgear.reload (op)
  Use /zcg reload
• zcustomgear.set.<id>, zcustomgear.talisman.<id> and zcustomgear.crate.<id>
  Required when that set, talisman or crate has require-permission: true

🧪 Requirements

• Minecraft: 1.18 to 1.21.11+ (single jar)
• Server software: Spigot or Paper
• Java: 17 or higher
• Optional: CoreJobs, EcoJobs, EconomyShopGUI, ItemsAdder, PacketEvents

📦 Installation

1. Drop the jar into your plugins/ folder.
2. Start the server once to generate the config, an example set, an example talisman, and an example crate.
3. Edit your sets, talismans and crates, then run /zcg reload.

First start needs internet once so the server can download the runtime libraries (cached afterward).

📈 Metrics

This plugin uses bStats to collect anonymous usage stats. You can opt out anytime in plugins/bStats/config.yml.

💬 Support

Need help, found a bug, or want to suggest a feature? Join the Discord. Full documentation is linked in the banner above.