API
Read homes, warps, kits, ranks and leaderboards, drive the teleports and claims, open the plugin's screens, and hear about home, warp, kit and rank-up changes.
SurvivalService is the part of ExyliaSurvivalCore another plugin can read or drive: spawn, random
teleport, homes, warps, kits, statistics, ranks, a few earnings helpers and six of the plugin's
screens. Six events sit alongside it, all cancellable, and they fire in front of the things that
change a player's world, so an integration can refuse one rather than clean up after it.
ExyliaAPI.get(SurvivalService.class).ifPresent(survival ->
survival.homes(player.getUniqueId())
.forEach(home -> player.sendMessage("Home: " + home.name())));The artifact, the repository and the plugin.yml line are the same for every Exylia plugin and live
on the public API page. Random teleport, kit gifts, the rank ladder and rank
costs and the menu openers arrived in exylia-api v1.133.0; toolForBreak, countStatistic and
isSettingEnabled came later. Compile against a recent tag to reach them all.
Crates, mines, bounties and duel rooms left this plugin, and so did their methods: the crate-key, bounty and mine-break methods remain in the interface as deprecated no-ops. Use the service of the plugin that owns them instead (ExyliaCrates, ExyliaMines, ExyliaCombat, ExyliaWarzone).
The plugin is a set of modules an administrator enables one by one, so a server can run the survival
core with no homes, no warps or no kits. Every method degrades when its module is off — an empty
list, an empty Optional, false, 0, or a no-op — and never throws. isModuleEnabled is how you
tell "no homes" from "no homes module". The menu openers are the exception that proves it: they tell
the player the module is off, the way the command does.
Everything that returns a value reads a cache and is safe from a menu redraw or a placeholder. Everything else teleports a player, gives them items, breaks a block, opens a screen or charges them money, and runs the same flow their own command or swing runs — including the permission checks and the messages they see — so call those on the thread that owns the player (or, for a block, the block) and no more often than a player could trigger them.
Modules#
| Method | What it does |
|---|---|
boolean isModuleEnabled(String moduleId) | Whether one module is running. |
Set<String> enabledModules() | Every module id that is running. |
The ids are the plugin's own vocabulary and the set grows between releases, so treat an unfamiliar
one as a module this integration does not know about rather than as an error. The ones behind this
service are spawn, rtp, homes, warps, kits, stats, rankup and playtime-rewards.
Spawn#
| Method | What it does |
|---|---|
Optional<Location> spawn() | Where the server spawn is. Empty when none is set or the module is off. |
void teleportToSpawn(Player player) | Sends a player there. |
Random teleport#
| Method | What it does |
|---|---|
void randomTeleport(Player player, String worldId) | Sends a player somewhere random in a world, as /rtp <world> does. For an NPC or a portal standing in for the command. |
worldId is the world's name as the random teleport configuration lists it. The world is checked
first — listed, enabled and loaded, or the player is told it was not found — then their cooldown and
their balance, and then the warmup runs exactly as the command's does, messages included. Nothing is
checked against exyliasurvivalcore.rtp, the permission /rtp itself asks for; the cooldown and
price bypass permissions still apply.
The search for a safe spot runs after the warmup, so the player lands a moment after the call returns, or not at all when they move or are hurt during it.
Homes#
| Method | What it does |
|---|---|
List<Home> homes(UUID player) | A player's homes. |
Optional<Home> home(UUID player, String name) | One of them by name, case insensitive. Empty when they have none by that name. |
int maxHomes(Player player) | How many they are allowed. Worked out from their permissions, so it needs the player rather than their id and changes when their rank does. |
void setHome(Player player, String name, Location location) | Creates or moves a home. Replaces one of the same name rather than adding a second, which is what the player's own command does. |
void deleteHome(UUID player, String name) | Removes a home. |
void teleportToHome(Player player, String name) | Sends a player to one of their homes. |
homes reads the cache, which holds a player's homes while they are online. An offline player's
homes are not cached, so it answers empty for them rather than going to the database on the calling
thread.
teleportToHome exists rather than leaving you to teleport to Home.location() yourself, because it
handles a home in an unloaded world or on another server — the two cases where that location is
null.
Warps#
| Method | What it does |
|---|---|
List<Warp> warps() | Every warp, enabled or not. |
Optional<Warp> warp(String warpId) | One by id. Empty when none has that id. |
boolean canUseWarp(Player player, String warpId) | Whether they hold the permission the warp needs. |
void teleportToWarp(Player player, String warpId) | Sends them there, charging, checking the permission and starting the warmup exactly as their own command does. |
long warpCooldownMillis(UUID player, String warpId) | Milliseconds until they may use it again. 0 when they may use it now. |
canUseWarp is permission only. A player who may use a warp can still be on cooldown for it or
unable to afford it, so it is what a menu greys a row out with, not a guarantee the teleport will
happen.
Kits#
| Method | What it does |
|---|---|
List<SurvivalKit> kits() | Every kit, enabled or not. |
Optional<SurvivalKit> kit(String kitId) | One by id. Empty when none has that id. |
KitClaimStatus kitStatus(Player player, String kitId) | Whether they could claim it right now, and why not. The same answer claimKit would give, worked out without giving anything — which is what a menu draws a row from. |
boolean claimKit(Player player, String kitId) | Gives them the kit. Runs every check first and gives nothing when one fails, so a refused claim costs neither a use nor a cooldown. |
boolean giveKit(Player player, String kitId, boolean ignoreLimits) | Gives them the kit as a reward rather than as a claim — a quest, a vote, a crate paying out a kit. claimKit is this with ignoreLimits false. |
long kitCooldownMillis(UUID player, String kitId) | Milliseconds until they may claim it again. |
int kitUsesLeft(UUID player, String kitId) | Claims left. -1 when the kit has no limit. |
With ignoreLimits true, giveKit skips the kit's cooldown and its use limit, the way an
administrator's give and a first-join kit do. The gift is still recorded, so it starts the cooldown
and counts as a use for the player's own next claim. Everything else is checked either way — the kit
being enabled, the player holding its permission and the room in their inventory — and both methods
fire KitClaimEvent and tell the player about a refusal exactly as the command does.
kitCooldownMillis and kitUsesLeft both answer 0 for somebody who is not online, and that is
deliberate rather than a gap. Kit progress is held per online player and dropped when they leave, so
asking about somebody absent has no answer to give and no reason to start holding one. 0 from
kitUsesLeft also means "no such kit", so check the player is online before reading either as a
number.
Statistics#
| Method | What it does |
|---|---|
Optional<SurvivalStats> stats(UUID player) | A player's combat counters. Empty when the statistics module is off. |
List<String> statistics() | Every statistic id that can be ranked. |
List<SurvivalRanking> leaderboard(String statisticId) | A statistic's leaderboard, best first. Empty when the statistic is unknown or has not been built yet. |
int rank(UUID player, String statisticId) | Their position, starting at 1. 0 when they are not ranked. |
long playtimeMillis(UUID player) | Milliseconds played. 0 when the module is off or they have never joined. |
The statistics are configured rather than fixed — an administrator can add one that reads a
placeholder from another plugin — so ask statistics() for the ids leaderboard accepts instead of
assuming a set.
leaderboard reads the podium the plugin keeps warm on a timer, so it is safe from a placeholder and
can be a few minutes behind.
playtimeMillis is the plugin's own total, which is what its playtime rewards are paid against — not
the server's session counter.
stats answers only for a player whose counters are loaded on this server, which means an online one.
For anybody else it is empty rather than a row of zeroes, which would be a wrong answer. Use
leaderboard for players who are away.
Ranks#
| Method | What it does |
|---|---|
List<Rank> ranks() | The whole ladder, lowest first. Empty when the module is off. |
Optional<Rank> currentRank(UUID player) | The rank they have reached. Empty when they are on none yet. |
Optional<Rank> nextRank(UUID player) | The rank they are working towards. Empty when they are at the top. |
int prestigeLevel(UUID player) | How many times they have prestiged. 0 when they never have. |
double nextRankCost(UUID player) | The money their next rank-up will charge. 0 when it is free, they are at the top, they are offline or the module is off. |
boolean canRankUp(Player player) | Whether they meet every requirement of their next rank. |
boolean rankUp(Player player) | Ranks them up, charging, running the reward commands and announcing it exactly as their own command does. |
canRankUp needs the player rather than their id: a requirement can be a permission or a placeholder
that only resolves against somebody online.
nextRankCost is the sum of the next rank's money requirements as this player pays them — multiplied
once per prestige level by the prestige cost multiplier (see
progression). It is money only: a rank can also ask for
playtime, a permission or a placeholder condition, so a player who can afford it may still be refused.
It reads the player's rank from the cache, which is why it answers 0 for somebody offline.
rankUp writes the promotion as a compare-and-set against the stored rank, so two servers cannot
promote the same player twice. A true can therefore arrive before the write is confirmed; in the rare
case another server promoted them first, the charge is refunded afterwards.
Earnings and shared counters#
These were the hooks mines and crops used to pay a player. Boosting moved to ExyliaLib's modifier
pipeline, autosell to ExyliaMarket and mines to ExyliaMines, so the old methods are deprecated and
answer neutrally (boostDrops returns the drops unchanged, payEarnings and autoSell return
false); each javadoc names its replacement. Three methods are live.
| Method | What it does |
|---|---|
ItemStack toolForBreak(Player player, ItemStack tool, Location at) | The tool a break is computed with after the enchantment limits of the place: a copy when a limit caps Fortune or Silk Touch there. Durability still belongs to the real item. |
void countStatistic(UUID player, String name, String key, long delta) | Adds to one of a player's counters, the ones missions, leaderboards and seasons read (protections.created, for example). |
boolean isSettingEnabled(UUID player, String key) | Whether a player keeps a setting on, such as an announcement they may mute. true unless they turned it off; a key the plugin does not know is on. |
Menus#
| Method | Opens | Permission checked |
|---|---|---|
void openKitsMenu(Player player) | The kit list, as /kit. | exyliasurvivalcore.kits |
void openWarpsMenu(Player player) | The warp list, as /warps. | exyliasurvivalcore.warps.use |
void openHomesMenu(Player player) | The player's homes, as /homes. | exyliasurvivalcore.homes |
void openRankUpMenu(Player player) | The rank ladder, as /rankup. | exyliasurvivalcore.rankup |
void openRandomTeleportMenu(Player player) | The world picker, as /rtp. | exyliasurvivalcore.rtp |
void openPlaytimeRewardsMenu(Player player) | The playtime rewards, as /playtime. | None. It runs /playtime of ExyliaRewards, so without that plugin the player is told the module is off. |
For an NPC, a sign or a lobby item leading into a screen. Each checks the permission its command asks for first, and a player without it gets the plugin's own no-permission message instead of the screen. A module that is off is also said to the player, the way the command says it, so a caller has nothing to explain either way.
openHomesMenu tells a player with no homes that they have none rather than showing an empty screen.
openRankUpMenu charges nothing: the screen shows progress and is where the player ranks up from.
Choosing a world in openRandomTeleportMenu starts the same flow as randomTeleport, cooldown, price
and warmup included.
Types#
Home — owner, name, location and iconMaterial (empty when it has none). location is
nullable, and that is the honest answer rather than a gap: a home can point at a world this server
has not loaded, or at another server entirely, and there is no Location for either. Use it to draw
a menu, and teleportToHome to travel.
Warp — id, displayName, enabled, cost (0 when free), permission (empty when anybody
may use it) and a nullable location, null for the same reason as a home's. Whether a particular
player may use it also depends on their cooldown, so ask canUseWarp and warpCooldownMillis rather
than deciding from cost and permission alone.
SurvivalKit — id, displayName, description, permission, cooldownMillis (0 when
there is no wait), maxUses and enabled. The contents are left out on purpose: they are an
ItemStack array the plugin owns and rewrites whenever an administrator edits the kit, and handing
one out would let a caller change what everybody gets. Claim the kit instead, or cancel
KitClaimEvent and give what you want yourself.
The record's javadoc says maxUses is 0 for no limit. The plugin passes the kit's own value
through, and it marks an unlimited kit with -1 — the admin editor stores any negative number as
-1, and the claim check treats only -1 as unlimited. A kit with maxUses 0 is refused with
MAX_USES_REACHED on the first claim. Read -1 as unlimited, which also matches kitUsesLeft.
KitClaimStatus — SUCCESS, NO_PERMISSION, ON_COOLDOWN, MAX_USES_REACHED, KIT_DISABLED,
KIT_NOT_FOUND (also returned when the kits module is not running) and NO_ROOM (it would not fit,
and the kit keeps what does not fit rather than dropping it). One set answers both "can this player
claim it" and "what happened when they did", because the reasons are the same — a claim is refused
before anything is given, so a player is never left with half a kit and a used-up cooldown.
SurvivalStats — player, kills, deaths, bestKillStreak and currentStreak. The four the
plugin stores itself. The wider statistics system can rank anything an administrator names, and those
are read one at a time through leaderboard(String) rather than fixed into a record.
SurvivalRanking — player, playerName, value and rank. value is a double whatever
the statistic counts, because the same machinery ranks kills, money and hours played. The plugin
formats it per statistic for its own menus; format the number yourself rather than depending on its
configuration.
Rank — id, displayName and order (lower sits earlier on the ladder). The requirements are
left out: they are read from configuration into the plugin's own types, and one of them can be an
arbitrary placeholder expression only the plugin knows how to evaluate. Ask canRankUp instead of
working the answer out, and nextRankCost for the money part.
Events#
Six events in net.exylia.lib.api.survival.event, all Cancellable, all fired before anything is
written, given, charged or moved — so cancelling leaves the player exactly as they were, with nothing
to undo. Cancelling also says nothing to the player: the handler that refused the action is the only
one that knows why, and is expected to say so itself.
| Event | Fires when |
|---|---|
HomeSetEvent | A player is creating or moving a home. |
HomeDeleteEvent | A home is about to be removed. |
HomeTeleportEvent | A player is travelling to one of their homes. |
WarpTeleportEvent | A player is travelling to a warp. |
KitClaimEvent | A player is claiming a kit, or being given one through giveKit. |
RankUpEvent | A player is moving up the rank ladder. |
BountyClaimEvent, MineBlockBreakEvent, MineResetEvent and DuelRoomEndEvent still exist in
exylia-api, but ExyliaCombat, ExyliaMines and ExyliaWarzone fire them now. Listen to them as
events of those plugins; this one fires none of them.
Does an uncancelled event mean it happened?#
| Event | Uncancelled means |
|---|---|
KitClaimEvent | It happens. Fired once every check has passed (enabled, permission, cooldown and uses unless giveKit skipped those two, room in the inventory) and before a single item is handed over. Cancelling gives no items, runs no reward commands, writes no cooldown and counts no use. |
HomeSetEvent | It happens. Fired once the world is allowed and, for a new home, the player is under their limit. Cancelling is the only thing that can still stop it. |
HomeDeleteEvent | It happens. Fired before anything is touched, so cancelling leaves the home exactly as it was. |
HomeTeleportEvent | Not a promise of arrival. A warmup can be walked out of or interrupted by damage, and the home can point at a world this server cannot resolve. |
WarpTeleportEvent | Not a promise of arrival. The warmup is cancelled if the player moves or is hurt, and the payment is only taken once it survives. Nothing is charged at event time. |
RankUpEvent | Not a promise of promotion. Payment is taken after the event and can still fail, and the player then stays where they are. Compare getTo() against currentRank(UUID) to know it landed. |
Both teleport events fire before the plugin decides whether the trip is instant or has a countdown, so cancelling stops the whole thing rather than only the jump at the end of a warmup.
Reading the events#
RankUpEvent.getFrom()is anOptional<Rank>, empty for a player who has never ranked up.getTo()is always there.HomeDeleteEvent.getPlayer()is aUUID, because a home can be deleted for somebody offline.HomeSetEvent.getLocation()is not necessarily where the player stands: the set can come from another plugin throughsetHome.getName()is the home's id, so reusing a name moves that home.- Every event is called on the thread that owns the player, which on Folia is a region thread. Anything touching the wider world has to be scheduled.
What it does not expose#
The plugin runs about thirty modules and this service reaches a handful. The rest (portals, back, repair, near, projects, reputation and the other quality-of-life modules) are player or administrator tools whose state is a set of placed objects or per-player settings, and there is nothing a third party could usefully do with them. Crates, mines, bounties, supply drops, regen zones, loot chests and duel rooms are other plugins now and publish their own services.
Within the modules it reaches, editor flows and administrative writes are left out, as are the kit contents and the rank requirements: both belong to the plugin and are rewritten whenever an administrator edits them. The only screens it opens are the six a player could open with their own command.
If something you need is missing, ask on Discord: a method added to a service is a minor release.
Something missing on this page? Tell us on Discord