Getting started

Installation

The loader jar and the licence, dependencies and what each optional plugin adds, the files the plugin writes, what goes to the database, languages and updating.

Getting the plugin

ExyliaSpecials is a premium plugin, bought on BuiltByBit. It ships through the Lukittu loader, so the file you install is the loader jar, Exylia-Specials-Loader.jar. Bought on BuiltByBit, the licence is embedded in that jar: there is no key to enter. The loader checks the licence on every start and then hands over to the plugin.

Version 4 is a rewrite. Nothing is read from a 3.x install: neither its configuration nor the items players already hold. See Coming from 3.x.

Before you start

Plugin	What for
`packetevents`	Required. Declared under `depend`, so without it the server does not load ExyliaSpecials at all. The packet decoys of summons are drawn with packets.
`ExyliaLib`	Required, version 1.448.0 or newer. Configuration, translations, item templates, effect lines, menus, regions, the database and client cooldown displays.

ExyliaLib is listed as soft, and installed for you

plugin.yml names ExyliaLib under softdepend on purpose: the loader is what installs it, so the loader has to be allowed to start without it. On a server without ExyliaLib it downloads the newest release into plugins/ and asks for a restart. On a server running an older release it stages the newest one and says so in the console; restart once more to apply it. Without network access, put ExyliaLib.jar in plugins/ by hand.

Optional plugins

Plugin	What it adds
`WorldGuard`	Region rules on items (`regions:` and region cooldowns), the PvP check before an ability touches another player, and the build check before a tool breaks or places a block. Without it every region rule passes and PvP is never considered denied.
`PlaceholderAPI`	The plugin's placeholders in other plugins, and PlaceholderAPI placeholders inside item lore and messages. See Placeholders.
`ExyliaCombat`, `DeluxeCombat` or `PvPManager`	The combat tag items read: Flight refused in combat, `combat-seconds` cooldowns, duel tags. ExyliaCombat also brings vanilla item cooldowns. See Combat.
`ExyliaMines`	Tools break blocks inside a mine through the mine, so mine resets, drops and stats stay right.
`FastAsyncWorldEdit`	Arena snapshots: an arena can then be restored after each duel and played as many copies at once. See Duels.
`Worlds`	On Folia, creates the temporary world that holds arena copies.

Installing

Drop in the jars

Exylia-Specials-Loader.jar and packetevents into plugins/. Add WorldGuard or PlaceholderAPI now if you want what they bring.

Start the server

The loader writes loader.yml, checks the licence and installs ExyliaLib if it is missing. If it had to install it, restart once more.

Let it generate

The plugin writes config.yml, its messages, the 70 item files, the 8 tracker files and the admin menus. The console prints Loaded 70 special items and ends with ExyliaSpecials enabled.

Try an item

Run /specialsadmin as an operator. See First steps.

Generated files

All of them live in plugins/ExyliaSpecials/.

File	Contents
`loader.yml`	Written by the loader. A BuiltByBit purchase needs nothing in it.
`config.yml`	Language, action bar, states and duels. See Configuration.
`lang/<language>/messages.yml`	Every line the plugin sends: chat, state bars, duel titles.
`lang/<language>/items/<id>.yml`	One special item or tool per file. See Special items.
`lang/<language>/trackers/<id>.yml`	One stat tracker per file. See Stat trackers.
`lang/<language>/menus/admin/*.yml`	The eight admin screens. Rewritten from the jar on every start and every reload.
`arenas.yml`	Duel arenas, written by `/specialsadmin arena` and the arena screens. Created with the first arena.
`schematics/arena_<id>.schem`	An arena's snapshot, when one was taken.
`database.yml`	Where rows are stored. Written by ExyliaLib.

Items live in the language folder

The item and tracker files that are read are the ones of the active language: with English, lang/en/items/. Switch language and the plugin reads lang/<new>/items/, a separate set of files — edits made to the English files do not follow. Pick the language first, then edit the items.

Languages

The plugin ships English, Spanish, French, Portuguese, Russian and Turkish: messages, menus, every item and every tracker. language: default in config.yml follows the language set in ExyliaLib's own config.yml; en, es, fr, pt, ru or tr set it for this plugin only. Any other code, such as custom, starts as a copy of English for you to translate.

A translation only carries the text of an item — its name, lore, texts and the names of its settings. The mechanics always come from the English file inside the jar, laid under the translation key by key, so every language plays the same.

What happens to the item and tracker files on start

On every start and every reload the plugin checks its bundled items and trackers against the folder of the active language:

A file that is missing is written again. Deleting a bundled item's file does not remove the item: it comes back on the next start. To retire one, give it a permission: nobody has.
Keys the jar has added since are added to your file. A default that changed in the jar waits in /exylialib updates instead of overwriting yours.
Your own edits are never touched.

Files of your own in the same folder are loaded too: any .yml there is an item.

The database

One thing is stored in the database database.yml points at — H2 in a file by default, or MySQL, MariaDB, PostgreSQL or MongoDB through ExyliaLib.

Table	Holds
`exylia_pending_rewards`	ExyliaLib's queue: items given to a player whose inventory was full, handed over on their next join.

Everything about an item — its id, uses left, expiry, tracker counts — is stored on the item itself, in one data key (exyliaspecials:data). Items keep their state in chests, ender chests and other servers.

Cooldowns are held in memory by ExyliaLib. Cooldowns of five minutes or more survive a restart; shorter ones do not.

Coming from 3.x

Version 4 shares nothing with 3.x. Configuration, item files and the data on items are all new, so:

start from a clean plugins/ExyliaSpecials/ folder;
special items handed out by 3.x stay plain vanilla items: they do nothing and cannot be converted. Give the new items again with /specialsadmin give item.

Updating

Replace the loader jar and restart. config.yml, messages, items and trackers keep your values; new keys are added with their defaults. The admin menus under menus/admin/ are rewritten from the jar on every start, so an edit there does not survive one.

Something missing on this page? Tell us on Discord