Ignite EquipmentPro - Equipment engine v1.0.0

What is IgniteEquipmentPro?

IgniteEquipmentPro is the premium successor to IgniteEquipmentEffects. It turns any Bukkit ItemStack into a fully programmable piece of equipment - passive effects, conditional gates, player-activated abilities, set bonuses, socketed gems, random rolls and item levelling - all driven by simple yaml files and reload-safe at runtime.

Every item runs through the same pipeline: PDC tag → scan → conditions → effects → triggers → abilities. There is no fragile name/lore matching, no per-event hardcoding, and no separate dependency plugin to install. Drop the jar in, restart, edit yaml. That is it.

The plugin is built 100% on IgniteAPI (shaded and relocated inside the jar), so it gets the same battle-tested config, scheduler, lifecycle, storage and ACF command stack as the rest of the Ignite Series.



Why "Pro"

• PDC item matching - PDC / STRICT / HYBRID per item, no more anvil-rename bypasses
• Real condition engine - 18 condition types + AND / OR / NOT trees instead of a fixed list
• 13 effect kinds - aura, trail, attribute, command, message, title, sound, particle, heal, damage and more
• 26 trigger types - tied directly to Bukkit events (combat, world, movement, lifecycle)
• Abilities - cooldown + charge + Vault cost executor with full gating
• Set bonuses - 2 / 4 / 6-piece tier bonuses with their own effects and console commands
• Sockets & gems - per-item socket list stored on PDC, gem effects compose at runtime
• Random rolls - weighted pool table, rolls stored on the item PDC
• Item XP + Level Rewards - per-equipment XP, milestone announcements, permanent unlocks, live tooltip with level/XP bar
• Three storage backends - YAML / SQL (SQLite + MySQL) / MongoDB
• In-game GUI editor - paginated browser, click any item to inspect or edit
• Standalone JAR - IgniteAPI is shaded, ACF is relocated, no extra plugins needed

How it works

1. Define - Drop a yaml file in plugins/IgniteEquipmentPro/items/ with id, item, conditions, effects, triggers, abilities
2. Tag - /eqpro give <id> hands out a PDC-tagged item that survives renames and item movement
3. Activate - The runtime scans worn / held items every tick, re-evaluates conditions and applies / removes effects automatically
4. Trigger - 26 trigger types fire on Bukkit events with their own cooldown, gate and effect list
5. Persist - Charges, cooldowns and item XP are saved per-player in the configured storage backend

Condition engine - 18 condition types

Conditions support both a shorthand AND form and full boolean trees. Every condition can be reused inside trigger and ability gates.

World & environment
WORLD · BIOME · TIME · WG_REGION

Player state
HEALTH_BELOW · HEALTH_ABOVE · XP_LEVEL · GAMEMODE · IN_COMBAT · PERMISSION

Movement & posture
SNEAKING · SPRINTING · FLYING · ON_GROUND · BLOCKING · IN_LIQUID

Items & integrations
HOLDING · PLACEHOLDER (PAPI compare)

Boolean nodes
AND · OR · NOT · ALWAYS · NEVER




Effect kinds - 13 built-in

• POTION - Vanilla potion effects, shorthand or map form, infinite or timed
• ATTRIBUTE - Add / multiply Bukkit attributes (MAX_HEALTH, ATTACK_DAMAGE, ...)
• AURA - Animated particle ring around the player
• TRAIL - Particle trail that follows the player's footsteps
• PARTICLE - One-shot particle burst on apply
• SOUND - Play a sound with custom volume / pitch
• MESSAGE - MiniMessage chat lines
• ACTION_BAR - MiniMessage action bar text
• TITLE - Title + subtitle with fade-in / stay / fade-out
• COMMAND - Console command list with {player} placeholder
• PLAYER_COMMAND - Run commands as the player
• HEAL - Heal the target a configurable amount
• DAMAGE - Damage the target or self if no target

Trigger types - 26 built-in

Each trigger has its own cooldown, gate condition, charge cost and effect list.

Lifecycle
ON_EQUIP · ON_UNEQUIP · PASSIVE

Interaction
ON_INTERACT · ON_RIGHT_CLICK · ON_LEFT_CLICK · ON_SHIFT_RIGHT_CLICK · ON_DOUBLE_RIGHT_CLICK

Combat
ON_KILL_PLAYER · ON_KILL_MOB · ON_DAMAGE_DEALT · ON_DAMAGE_TAKEN · ON_PROJECTILE_HIT · ON_SHOOT_BOW

World
ON_BLOCK_BREAK · ON_BLOCK_PLACE · ON_FISH · ON_EAT

Movement
ON_SNEAK_START · ON_SNEAK_END · ON_SPRINT_START · ON_SPRINT_END · ON_JUMP · ON_FALL · ON_RESPAWN

Reactive
ON_HEALTH_BELOW (hysteresis-debounced - fires on the falling edge) · ON_COMBO (rapid melee hit chain inside a 1.5s window)



Abilities

Player-activated effect bundles. Each ability passes through AbilityExecutor which checks - in this exact order - permission, gate, cooldown, charges and Vault money. Charges and money are deducted only on success.

• Activation - ON_RIGHT_CLICK · ON_SHIFT_RIGHT_CLICK · ON_LEFT_CLICK · ON_INTERACT
• Cooldown - per ability, persisted across sessions
• Charge cost - decouples activation count from cooldowns
• Money cost - Vault withdraw on success
• Gate condition - full condition expression, same engine as passive conditions
• Effects + console commands + player commands - all run on success

Set bonuses

plugins/IgniteEquipmentPro/sets/<id>.yml declares a set, its member ids and tier-bonus thresholds (2 / 4 / 6 pieces). Bonuses stack: wearing 4 pieces activates both the 2-piece and 4-piece bonuses.




Sockets & gems

Gems are their own yaml files. Each socket on an equipment can hold one gem id and the gem's effects are layered on top of the equipment's passive effects at apply time. Socket lists are stored per item instance on the PDC, so two copies of the same equipment can have totally different gems.

• /eqpro socket <equipment-id> <gem-id> - attaches a gem to the held equipment
• Minimum gem tier - sockets can require COMMON / UNCOMMON / RARE / EPIC / LEGENDARY / MYTHIC
• Empty sockets - declared in config and ignored at runtime

Random rolls

Define a weighted pool on an equipment, then hand the item out with /eqpro give-random <id>. The runtime picks the configured number of rolls weighted by weight, stores them on the item PDC and applies each rolled effect on top of the passive effect set.




Item XP & Level Rewards

Every equipment can level up. XP is tracked per (player, equipment) in the configured storage backend, the curve is floor(sqrt(xp / 100)) (override the formula in ItemLevels), and every level threshold can grant permanent unlocks AND fire a one-shot milestone - all driven by the same yaml the rest of the plugin already speaks.

Step 1 - earn XP via the per-event reward block:


Step 2 - reward levels with permanent unlocks and one-shot milestones:


Unlock anatomy - both unlocks and on-level-up.effects reuse the standard effect list. That means every effect kind the plugin supports already works as a level reward - potions, attributes, auras, trails, heals, damage, sounds, titles, action bars, commands.

• unlocks - applied alongside the base passive effects while the equipment is worn AND the player's item-level is at or above the threshold. Symmetrically removed when the item is unequipped or the player de-levels (rollback / debug)
• on-level-up - fires the moment the player crosses the threshold, even if they jump multiple levels in one XP grant (e.g. an admin-given big XP chunk triggers every milestone in order)
• Generic level-up title - if a level has no on-level-up block defined the plugin still shows a tasteful default LEVEL UP title, so progression always feels confirmed

Step 3 - watch progress in the tooltip. The lore template supports inline + block placeholders that the renderer expands on every XP gain, on join, and after every pickup:

• {xp-level} - current level
• {xp-current} / {xp-next} - current XP / XP needed for next level
• {xp-percent} - 0-100 progress to next level
• {xp-bar} - 12-character green/dark-gray progress bar
• {xp} - block-expands into the configured XP reward table
• {levels} - block-expands into the milestone list, with check / cross icons reflecting unlock status

Example rendered lore:


Live updates - no PAPI required. The lore is rewritten on the actual ItemStack via ItemPresentation.apply():

• After every XP gain - new level / XP / bar immediately visible
• On player join - so XP saved from the previous session surfaces straight away
• After EntityPickupItemEvent - dropped items show the new owner's progress, not the previous holder's
• After /eqpro give and /eqpro socket - the handed-out item starts with the receiver's accumulated XP rendered correctly

PAPI bonus (optional, for HUDs and scoreboards): %eqpro_xp_<id>% and %eqpro_level_<id>% are still exposed - use them in sidebars, holograms, action bars or chat formats outside the tooltip.

Why it works without bloat:

• One effect engine - level unlocks and one-shots reuse the same ItemEffect list as passive effects, triggers and abilities. Add a new effect kind once, it works everywhere
• Sorted thresholds - levels are sorted at parse time so iteration is O and the unlock check is a single pass
• Multi-level crossings - if a single XP grant jumps from Lv 4 → Lv 12 the listener fires every milestone in (4, 12] in order
• No new persistence layer - levels are derived from XP, so storage is exactly itemXp - one upsert per gain

Storage backends

Same interface, same persisted fields (cooldowns, charges, item XP, bindings). Pick the backend that fits your network.

• YAML - one file per player, zero-config, ideal for single servers
• SQLITE - file-backed database, drop-in upgrade with no setup
• MYSQL - HikariCP pool, cross-server progress for BungeeCord / Velocity networks
• MONGODB - one document per player, driver bundled and relocated inside the jar

Async writes. SQL and Mongo upserts go through Async.fireAndForget so the main thread never blocks on JDBC. Reads stay consistent thanks to a synchronous in-memory cache. If a remote backend fails to initialize the plugin falls back to an in-memory repository and logs a single warning, so the rest of the plugin always boots cleanly.



PlaceholderAPI

Identifier: eqpro. Placeholders are cached for 500 ms.

• %eqpro_active_count% - number of currently-active equipment
• %eqpro_active_ids% - comma-separated list of active ids
• %eqpro_charges_<id>% - current charges on equipment
• %eqpro_cooldown_<id>_<ability>% - seconds left on ability cooldown
• %eqpro_set_pieces_<setId>% - pieces worn from a set
• %eqpro_xp_<id>% - item XP on the given equipment
• %eqpro_level_<id>% - computed level from item XP

Integrations

Every optional integration is soft-loaded. Missing plugins are detected at runtime, a single line is logged and the plugin keeps running unchanged.

• IgniteAPI - bootstrap, configs, lifecycle, storage, GUI, ACF (shaded and relocated)
• PlaceholderAPI - PLACEHOLDER condition + the %eqpro_*% expansion
• Vault - money costs on ability activation
• LuckPerms - hooks reserved for future context conditions
• WorldGuard - WG_REGION condition
• MythicMobs - reserved hook for future Mythic skill triggers

Bundled defaults - 11 items, 3 sets, 5 gems

The plugin's data folder is pre-populated on first boot so admins have something to spawn and inspect immediately. Every file is editable yaml - keep, rebalance, or delete to taste.

Items

• SPEED_BOOTS / SPEED_HELMET / SPEED_CHESTPLATE / SPEED_LEGGINGS - the full Speedster armor set (RARE)
• BERSERKER_AXE - EPIC mainhand with ON_KILL_MOB rage, ON_COMBO surge and a damage aura
• BERSERKER_HELMET - EPIC helmet, intimidation smoke aura + flat damage bonus
• GUARDIAN_SHIELD - EPIC off-hand, resistance while blocking + ON_HEALTH_BELOW shout
• GUARDIAN_CHESTPLATE - EPIC chestplate, +6 HP / +2 armor and an equip flourish
• PHOENIX_AMULET - LEGENDARY hotbar trinket, charge-gated Rebirth ability and fire aura
• MINERS_PICKAXE - UNCOMMON pickaxe, ON_BLOCK_BREAK XP, vein-sense haste, random roll table
• ANGLERS_ROD - UNCOMMON rod, in-water luck + dolphin's grace + ON_FISH jackpot

Sets

• speedster - 4-piece, layered movement bonuses
• berserker - 2-piece, in-combat Strength + bonus melee damage
• guardian - 2-piece, always-on Resistance + armor toughness

Gems

• fire_gem - fire resistance + flame aura
• water_gem - water breathing + dolphin's grace + drip aura
• earth_gem - resistance + slow falling + dust aura
• wind_gem - speed + jump + cloud aura
• lightning_gem - haste II + electric spark aura

In-game editor

/eqpro editor opens a paginated browser. Click any equipment to inspect its full configuration - Info, Effects, Conditions, Triggers, Abilities. Every edit is written back to the source yaml and logged to audit.log.

• Info - cycle tier, cycle match mode, toggle bind-on-use, toggle non-marketable, reload from disk
• Effects - shift-click any effect to delete it from the yaml list
• Triggers - left-click bumps cooldown +5s, right-click -5s, shift-click deletes the trigger
• Abilities - left-click test-fires through the executor, right-click bumps cooldown, shift left-click deletes

Restructuring full condition trees still goes through yaml + /eqpro reload - reload is hot, no restart needed.



Commands

Alias: /eqpro · /igniteequipmentpro · /iep

• /eqpro - Show command list
• /eqpro new <id> - Create new equipment from the held item + open editor
• /eqpro give <id> [player] - Give equipment to a player
• /eqpro give-random <id> [player] - Give an item with rolled effects from its roll-table
• /eqpro create <id> - Tag the held item with an existing equipment id (PDC)
• /eqpro socket <equipment-id> <gem-id> - Socket a gem into the held equipment
• /eqpro list - List loaded equipment (click an entry to give)
• /eqpro reload - Hot-reload configs, equipment, sets and gems
• /eqpro debug [player] - Show active equipment + condition-passing equipment for a player
• /eqpro editor [id] - Open paginated browser or jump straight to one equipment

Permissions

• igniteequipmentpro.admin - Bundles every child permission (default: op)
• igniteequipmentpro.give - /eqpro give, give-random, create (default: op)
• igniteequipmentpro.edit - /eqpro new, socket, editor (default: op)
• igniteequipmentpro.reload - /eqpro reload (default: op)
• igniteequipmentpro.list - /eqpro list (default: op)
• igniteequipmentpro.debug - /eqpro debug (default: op)

API for other plugins


Equipment, Trigger, Ability, Condition and ItemEffect are immutable data classes - safe to read from any thread. EquipmentService.update and TriggerDispatcher.fire must run on the main thread because they touch Bukkit state.



Requirements

• Paper / Folia: 1.21+
• Java: 21
• Optional: PlaceholderAPI · Vault + economy provider · LuckPerms · WorldGuard 7.0+ · MythicMobs

Standalone JAR. IgniteAPI, ACF, bStats and the JDBC / Mongo drivers are all shaded and relocated inside the plugin jar. No separate IgniteAPI plugin, no library loader setup, no manual jar install on the server.



Perfect for

• Survival and SMP servers
• Lifesteal SMP servers
• UHC and PvP event servers
• RPG and progression servers
• Hardcore event servers
• Skyblock and dungeon servers
• Servers with custom item economies
• Developers building custom equipment systems on top of a single API

Why choose IgniteEquipmentPro?

Most equipment plugins are still stuck on name + lore matching, hardcoded condition lists and one fixed effect type. IgniteEquipmentPro is built differently: PDC-tagged items, a real condition tree, 13 stackable effect kinds, 26 trigger types and an ability executor with proper gating - all driven by yaml, all hot-reloadable, all exposed through a stable API.

Define. Tag. Activate. Trigger. Persist.