Public API
One artifact the whole Exylia suite answers through: add it, look a service up, listen for its events.
Every Exylia plugin publishes its API the same way. There is one artifact to add, one class to call, and one rule to follow — and once you know it for one plugin you know it for all of them.
Adding it to your build#
The API is published from the ExyliaLib repository through JitPack.
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
compileOnly 'com.github.DiGround-s.ExyliaLib:exylia-api:v1.321.2'
}repositories {
maven("https://jitpack.io")
}
dependencies {
compileOnly("com.github.DiGround-s.ExyliaLib:exylia-api:v1.321.2")
}<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>com.github.DiGround-s.ExyliaLib</groupId>
<artifactId>exylia-api</artifactId>
<version>v1.321.2</version>
<scope>provided</scope>
</dependency>
</dependencies>The version is the ExyliaLib release tag, v included — use the tag of the ExyliaLib the server
runs, or an older one. Sources and javadoc are published alongside it, so your IDE shows the
documentation for every method without leaving the editor.
The contract carries a version of its own, 3.1.0 today, which is what the @since tags in the
javadoc count in (@since 1.10.0 on CratesService is exylia-api 1.10.0, not ExyliaLib 1.10.0).
See Versioning.
compileOnly — provided in Maven — is required, and shading the artifact into your own jar breaks
it. These classes already ship inside ExyliaLib.jar on the server. A second copy in your jar is
loaded by your classloader, which makes it a different class than the one the plugins implement,
and every lookup returns nothing. There is no error message; it simply never finds anything.
Declaring the library#
ExyliaLib has to be enabled before you, and your plugin has to be allowed to see its classes. One
line in your plugin.yml does both:
depend: [ ExyliaLib ]Use softdepend instead if your plugin should still load on a server without ExyliaLib. Then guard
every call with the Optional the lookup already hands you.
Looking a service up#
Everything goes through net.exylia.lib.api.ExyliaAPI.
ExyliaAPI.get(ClansService.class)
.flatMap(clans -> clans.clanOf(player.getUniqueId()))
.ifPresent(clan -> player.sendMessage("Clan: " + clan.name()));| Call | For |
|---|---|
get(Service.class) | A soft integration. Returns Optional, empty when the plugin is absent, disabled, or still enabling. |
require(Service.class) | A hard depend on the plugin behind the service. Throws IllegalStateException when it is not there. |
isAvailable(Service.class) | A capability check, without unwrapping anything. |
A service registers when its plugin enables, and server load order is not yours to choose. Looking
one up inside your own onEnable may well ask before the other plugin has started. Resolve it at the
point of use — the lookup is a map read — or from ServerLoadEvent.
Listening for events#
Plugins that have something worth reacting to publish real Bukkit events, in the same artifact, under
net.exylia.lib.api.<plugin>.event. They are registered like any other listener:
@EventHandler
public void onKitClaim(KitClaimEvent event) {
if (isTournamentRunning()) event.setCancelled(true);
}Cancelling means the action does not happen and no message is sent — telling the player why is yours to do. Each event's javadoc says whether an uncancelled event guarantees the action went through: some do, and some sit in front of a step that can still fail, such as a payment or a teleport warmup a player can walk out of.
Why the contract lives in the library#
Worth knowing, because it explains the compileOnly rule and why there is one artifact rather than
twenty.
Every Exylia plugin ships as a loader jar: the server loads a small loader, which decrypts the real
plugin into a classloader of its own. Bukkit's dependency delegation reaches that loader and stops
there — so an interface shipped inside a plugin is invisible to every other plugin, whatever the
plugin.yml files say, and a copy shipped in both is two unrelated classes.
ExyliaLib is the one jar every plugin on the server can already see. So the contract lives there, and
exylia-api is the same classes packaged for you to compile against.
The services#
| Service | Plugin | Package |
|---|---|---|
AimTrainerService | ExyliaAimTrainer | net.exylia.lib.api.aimtrainer |
ArmorSkinService | ExyliaArmorSkin | net.exylia.lib.api.armorskin |
ArmorTrimService | ExyliaArmorTrims | net.exylia.lib.api.armortrims |
ArrowsService | ExyliaArrows | net.exylia.lib.api.arrows |
CaptureService | ExyliaCapture | net.exylia.lib.api.capture |
ChatService | ExyliaChatCosmetics | net.exylia.lib.api.chatcosmetics |
ClansService | ExyliaClans | net.exylia.lib.api.clans |
ClassesService | ExyliaClasses | net.exylia.lib.api.classes |
CosmeticsService | ExyliaChatCosmetics | net.exylia.lib.api.chatcosmetics |
CratesService | ExyliaCrates | net.exylia.lib.api.crates |
EventsService | ExyliaEvents | net.exylia.lib.api.events |
FfaService | ExyliaFFA | net.exylia.lib.api.ffa |
HitEffectService | ExyliaHitEffect | net.exylia.lib.api.hiteffect |
KillEffectService | ExyliaKillEffect | net.exylia.lib.api.killeffect |
MarketService | ExyliaMarket | net.exylia.lib.api.market |
MinesService | ExyliaMines | net.exylia.lib.api.mines |
PearlsService | ExyliaPearls | net.exylia.lib.api.pearls |
PracticeBotService | ExyliaPracticeBot | net.exylia.lib.api.practicebot |
PracticeService | ExyliaPracticeCore | net.exylia.lib.api.practice |
ProtectionsService | ExyliaProtections | net.exylia.lib.api.protections |
SandBoxService | ExyliaSandBox | net.exylia.lib.api.sandbox |
ShieldsService | ExyliaShields | net.exylia.lib.api.shields |
SpecialsService | ExyliaSpecials | net.exylia.lib.api.specials |
StaffService | ExyliaStaff | net.exylia.lib.api.staff |
SurvivalService | ExyliaSurvivalCore | net.exylia.lib.api.survival |
TableService | ExyliaTabletop | net.exylia.lib.api.tabletop |
TotemTrainerService | ExyliaTotemTrainer | net.exylia.lib.api.totemtrainer |
| — | ExyliaTotems | net.exylia.lib.api.totems |
A few worth knowing from here, before opening the plugin's own page:
- ExyliaTotems has events and no service.
PlayerTotemHoldEventfires before a dying player's death is held open to see whether they reached for a totem in time — a plugin running its own deaths cancels it — andPlayerTotemSaveEventafter a save. The death is cancelled, so neitherPlayerDeathEventnorEntityResurrectEventreaches a listener; these two are the whole API. EventsServicetakes minigames of your own.net.exylia.lib.api.events.customis the one place in the artefact where a plugin declares something for another to run rather than reading it:registerMinigameadds a minigame that ExyliaEvents sets up and plays like a built-in. See ExyliaEvents · Registering your own minigame.MinesService.breakBlockis for plugins that break blocks on a player's behalf (a 3x3 pickaxe, a vein miner): inside a mine the server's break event is always cancelled, so hand every block here and break it yourself only onMineBreakResult.UNCLAIMED.MineBlockDropEventhands a listener the drops a mine is about to give, to change them or switch auto-pickup.MarketService.autoSell(player, drop)offers a drop to the player's autosell;truemeans it was sold and must not be given as well. Market events:MarketDealEvent(a deal settled),TradeRequestEvent, the cancellableSellWandUseEvent(cancel it for a container that decides itself when it opens), andMarketLogEvent, deprecated — plugins record into ExyliaLib's staff log now.SurvivalServicealso carries what the survival core shares with other plugins:countStatisticadds to the counters missions, leaderboards and seasons read, andisSettingEnabledreads a player's settings, such as announcements they muted. Its mine, crate and autosell methods are deprecated in favour ofMinesService,CratesServiceandMarketService, and its drop, experience and money boosts in favour of ExyliaLib'sModifiers.TableServicedescribes ExyliaTabletop's player-versus-player matches: its games (TableGameInfo), live matches and open offers (TableMatchsnapshots with theirTableSeats and aMatchState), a player's record (TableStats), and actions that run the player's own command flow (openLobby,createOffer,duel,join,forfeit) and return before the stake is taken;cancelcalls a match off and refunds it. Listen forTableMatchCreateEventandTableMatchJoinEvent(cancellable, before anything is charged),TableMatchStartEvent, andTableMatchEndEventfor the outcome: the winner, theEndReason, the prize and the server's fee.
What a service drives#
A service does more than answer questions:
- On-demand actions go through the same path the plugin's own trigger uses — a kill effect played without a kill, a kit given as a reward, a special item activated without holding it. The gates a real trigger passes still apply, and each method's javadoc says which ones it skips.
- Menu openers open a player-facing screen exactly as its command does, so an NPC, a sign or a lobby item can lead into it.
- Result enums replace booleans where a call can be refused for more than one reason
(
DuelStartResult,EnterResult,MineBreakResult, …). - Cancellable events fire after the plugin's own checks and before anything is written, so a cancelled event leaves nothing half done.
What is not there#
Every service is curated rather than a mirror of the plugin's internals. Editor flows, administrative writes, anything that spends a player's money on their behalf and raw configuration rows are left out on purpose: a public contract cannot be broken lightly, so it holds what an integration genuinely needs and nothing that only made sense inside one version of one plugin.
If something you need is missing, ask on Discord rather than reaching for reflection — a method added to a service is a minor release, and reflection into a loader plugin does not work in the first place.
Versioning#
exylia-api follows semantic versioning independently of ExyliaLib's own version, and its version
moves only when the contract does. New methods and new services are minor releases and never break a
caller. A deprecated method keeps working, usually by forwarding to what replaced it.
A major release is rare and says what it replaced. 3.0.0 removed net.exylia.lib.api.betcore: its
plugin became ExyliaTabletop, whose player-versus-player matches are described by
net.exylia.lib.api.tabletop (BetCoreService is now TableService, BetMatch is TableMatch, the
BetMatch*Events are TableMatch*Events), and the games played against the server are no longer part
of the contract.
Compiling against an older tag than the server runs is fine. The reverse is not: a method added in a
newer API is not in an older ExyliaLib.jar, and finds nothing at runtime.
Something missing on this page? Tell us on Discord