Content generated with AI — it may contain mistakes.

ExyliaLib/Referenceguide

Public API

One artifact the whole Exylia suite answers through: add it, look a service up, listen for its events.

Page 50 of 548 min read

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.

build.gradle
groovy
repositories {
    maven { url 'https://jitpack.io' }
}
 
dependencies {
    compileOnly 'com.github.DiGround-s.ExyliaLib:exylia-api:v1.321.2'
}
build.gradle.kts
kotlin
repositories {
    maven("https://jitpack.io")
}
 
dependencies {
    compileOnly("com.github.DiGround-s.ExyliaLib:exylia-api:v1.321.2")
}
pom.xml
xml
<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 is not a style choice

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:

plugin.yml
yaml
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.

java
ExyliaAPI.get(ClansService.class)
         .flatMap(clans -> clans.clanOf(player.getUniqueId()))
         .ifPresent(clan -> player.sendMessage("Clan: " + clan.name()));
CallFor
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.
Resolve where you use it, not in onEnable

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:

java
@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#

ServicePluginPackage
AimTrainerServiceExyliaAimTrainernet.exylia.lib.api.aimtrainer
ArmorSkinServiceExyliaArmorSkinnet.exylia.lib.api.armorskin
ArmorTrimServiceExyliaArmorTrimsnet.exylia.lib.api.armortrims
ArrowsServiceExyliaArrowsnet.exylia.lib.api.arrows
CaptureServiceExyliaCapturenet.exylia.lib.api.capture
ChatServiceExyliaChatCosmeticsnet.exylia.lib.api.chatcosmetics
ClansServiceExyliaClansnet.exylia.lib.api.clans
ClassesServiceExyliaClassesnet.exylia.lib.api.classes
CosmeticsServiceExyliaChatCosmeticsnet.exylia.lib.api.chatcosmetics
CratesServiceExyliaCratesnet.exylia.lib.api.crates
EventsServiceExyliaEventsnet.exylia.lib.api.events
FfaServiceExyliaFFAnet.exylia.lib.api.ffa
HitEffectServiceExyliaHitEffectnet.exylia.lib.api.hiteffect
KillEffectServiceExyliaKillEffectnet.exylia.lib.api.killeffect
MarketServiceExyliaMarketnet.exylia.lib.api.market
MinesServiceExyliaMinesnet.exylia.lib.api.mines
PearlsServiceExyliaPearlsnet.exylia.lib.api.pearls
PracticeBotServiceExyliaPracticeBotnet.exylia.lib.api.practicebot
PracticeServiceExyliaPracticeCorenet.exylia.lib.api.practice
ProtectionsServiceExyliaProtectionsnet.exylia.lib.api.protections
SandBoxServiceExyliaSandBoxnet.exylia.lib.api.sandbox
ShieldsServiceExyliaShieldsnet.exylia.lib.api.shields
SpecialsServiceExyliaSpecialsnet.exylia.lib.api.specials
StaffServiceExyliaStaffnet.exylia.lib.api.staff
SurvivalServiceExyliaSurvivalCorenet.exylia.lib.api.survival
TableServiceExyliaTabletopnet.exylia.lib.api.tabletop
TotemTrainerServiceExyliaTotemTrainernet.exylia.lib.api.totemtrainer
—ExyliaTotemsnet.exylia.lib.api.totems

A few worth knowing from here, before opening the plugin's own page:

  • ExyliaTotems has events and no service. PlayerTotemHoldEvent fires 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 — and PlayerTotemSaveEvent after a save. The death is cancelled, so neither PlayerDeathEvent nor EntityResurrectEvent reaches a listener; these two are the whole API.
  • EventsService takes minigames of your own. net.exylia.lib.api.events.custom is the one place in the artefact where a plugin declares something for another to run rather than reading it: registerMinigame adds a minigame that ExyliaEvents sets up and plays like a built-in. See ExyliaEvents · Registering your own minigame.
  • MinesService.breakBlock is 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 on MineBreakResult.UNCLAIMED. MineBlockDropEvent hands 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; true means it was sold and must not be given as well. Market events: MarketDealEvent (a deal settled), TradeRequestEvent, the cancellable SellWandUseEvent (cancel it for a container that decides itself when it opens), and MarketLogEvent, deprecated — plugins record into ExyliaLib's staff log now.
  • SurvivalService also carries what the survival core shares with other plugins: countStatistic adds to the counters missions, leaderboards and seasons read, and isSettingEnabled reads a player's settings, such as announcements they muted. Its mine, crate and autosell methods are deprecated in favour of MinesService, CratesService and MarketService, and its drop, experience and money boosts in favour of ExyliaLib's Modifiers.
  • TableService describes ExyliaTabletop's player-versus-player matches: its games (TableGameInfo), live matches and open offers (TableMatch snapshots with their TableSeats and a MatchState), 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; cancel calls a match off and refunds it. Listen for TableMatchCreateEvent and TableMatchJoinEvent (cancellable, before anything is charged), TableMatchStartEvent, and TableMatchEndEvent for the outcome: the winner, the EndReason, 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