Introduction
What ExyliaSpecials is, what it covers, what it needs to run and how this documentation is organised.
ExyliaSpecials is a plugin of special items: items that do something when a player right-clicks, hits, eats, throws, sneaks, breaks a block or simply carries them. A freeze that locks everyone around you in place, a pickaxe that mines 3×3, a compressor that folds ores into blocks from anywhere in the inventory, a summoned bard that buffs you, an item that drags the player you hit into a 1v1.
Every item is one YAML file. Its behaviour is a list of features: an ability is a chain of steps written in the plugin's own action language (target, damage, push, give a state, place temporary blocks, summon, start a duel...), and a tool feature is a ready-made behaviour with a few keys (area break, vein miner, tree capitator, auto smelt, compressor...). 70 items ship ready to use, and every number in them can be changed from a form in game.
Around the items the plugin brings stat trackers that count kills or blocks on any item, and duel arenas for the items that start a fight. The combat tag and vanilla item cooldowns live in ExyliaCombat; the items read the tag of whichever combat plugin is installed.
It is a premium plugin, sold on BuiltByBit and installed through a licence loader.
What is included
One file per item: the item itself, settings editable in game, limits by uses or time, cooldowns, region rules and the features that run on each trigger.
Action languageForty steps to target players, deal damage, move them, give effects and states, place blocks, summon allies and start duels.
Bundled itemsThe 70 items that ship with the plugin, what each one does and the settings it exposes.
ToolsFifteen tool behaviours: area break, vein miner, tree capitator, replant, till, compressors, void filter, infinite buckets, magnet, telekinesis and more.
Stat trackersItems that, clicked onto a sword, pickaxe or rod, count kills, blocks, arrows, damage or fish on it.
Combat, cooldowns and duelsHow items read the combat tag, special item cooldowns and duel arenas.
Requirements
| Requirement | Detail |
|---|---|
| Server | Paper 1.21.1 or newer, or a fork of it; Folia 1.21.4 or newer. Mannequin summon bodies need 1.21.9 and fall back to their fallback entity before it. |
| Java | 21 |
| Required dependencies | packetevents, and ExyliaLib 1.448.0 or newer — installed for you if it is missing |
| Optional dependencies | WorldGuard, PlaceholderAPI, ExyliaCombat, DeluxeCombat or PvPManager, ExyliaMines, FastAsyncWorldEdit |
Configuration and translations, the item templates, the effect lines every ability plays, the menus, the regions of the duel arenas, the database and the cooldown display on Lunar and Feather clients all come from ExyliaLib. ExyliaSpecials is written on top of it and does not run without it, which is why the loader installs it on a server that lacks it.
How an item works, in one paragraph
A player uses an item. The plugin finds the features of that item bound to what just happened — a right-click, a hit, a sneak — and checks them in a fixed order: silenced, permission, region, combo, cooldown, uses or expiry. If they pass, the feature runs; if it finished its job, the item's cooldown starts and a use is spent. When the last use is spent the item is gone. Every number on the item's lore comes from the same values the feature reads, so the lore never lies about the item.
How to read this documentation
Getting started
Installation, then giving yourself an item, changing a value in game and writing a first item of your own.
Special items
The item file, the action language, the states, every bundled item, the tool features and the stat trackers.
Systems
The combat tag, item cooldowns and duels.
Reference
Commands, permissions, placeholders, every configuration key, the developer API and the questions that come up most.
Conventions
- Values marked as default are what the plugin writes the first time it starts. If a file already exists, your values are kept.
- Identifiers between
<and>are variables./specialsadmin give item <id>means/specialsadmin give item freeze, not/specialsadmin give item <freeze>. - An item's id is its file name unless the file sets
id:. Its display name is what messages and menus call it. - Colours use ExyliaLib palette tokens (
{primary},{info},{letters}), and&codes work too. - Durations in
config.ymltake a bare number of seconds or a length such as15sor1m30s.
Something missing on this page? Tell us on Discord