API

SurvivalService is the part of ExyliaSurvivalCore another plugin can read or drive: spawn, random teleport, homes, warps, kits, crate keys, statistics, ranks, bounties, mine blocks and six of the plugin's screens. Ten events sit alongside it. Eight are cancellable and fire in front of the things that change a player's world, so an integration can refuse one rather than clean up after it; the other two report a duel or a mine reset that has already happened.

ExyliaAPI.get(SurvivalService.class).ifPresent(survival ->
    survival.homes(player.getUniqueId())
            .forEach(home -> player.sendMessage("Home: " + home.name())));

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 mine block, the block) and no more often than a player could trigger them.

Modules

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, crates, stats, rankup, playtime-rewards, mines and bounties, and duel-rooms fires one of the events.

Spawn

Random teleport

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

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

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

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.

Crates

crateKeys counts the balance only. Physical key items in an inventory are items like any other and are not counted. The balance is held per online player, so an offline player reads as 0 rather than the database being read on the calling thread.

giveCrateKeys is for a vote listener, a store or an event payout, and works on a player who is offline or on another server. Their balance is loaded first, so a give never writes a row built from zero over the keys they already had. For somebody already loaded on this server the keys land immediately; for anybody else they land once that read finishes, a moment after true comes back. The player is told nothing.

Statistics

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.

Ranks

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.

Mines

For plugins that break blocks on a player's behalf — a 3x3 pickaxe, a vein miner. Inside a mine the server's own block break is always cancelled and the mine removes the block itself, so breaking a block there any other way skips the mine's permission, its loot and its regeneration, and leaves a hole the mine never refills. Hand every block here first and break it yourself only on UNCLAIMED.

The mine checks its permission, fires MineBlockBreakEvent, and breaks the block with the item in the player's main hand: its enchantments shape the vanilla drops (Fortune, Silk Touch) unless the block has a custom loot table, and it loses durability either way. A player holding exyliasurvivalcore.mines.admin passes both the permission and the restriction. The player is told nothing when the mine refuses — a caller refused on eight blocks at once is the one that knows whether that is worth a message.

Bounties

Bounties are all held in memory, so this answers for an offline player too.

Menus

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.

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.

MineBreakResult — what became of a block handed to breakMineBlock. Only UNCLAIMED leaves the block to the caller; every other value means a mine owns it and the caller must not break it any other way.

Events

Ten events in net.exylia.lib.api.survival.event. Eight are Cancellable, and those eight fire before anything is written, given, charged, moved or broken — so cancelling leaves the player exactly as they were, with nothing to undo. The other two report something already done.

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.

Does an uncancelled event mean it happened?

For the eight that can be cancelled, it depends on what stands between the event and the result.

HomeTeleportEvent is fired 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. WarpTeleportEvent does the same, which is why a handler never leaves a player standing through a warmup that goes nowhere.

Reading the events

• RankUpEvent.getFrom() is an Optional<Rank> and is empty for a player who has never ranked up. The first promotion starts from no rank at all rather than from a bottom rung, and there is no sensible Rank to name for it. getTo() is always there.
• HomeDeleteEvent.getPlayer() is a UUID rather than a Player, because a home can be deleted for somebody who is not online — an administrator command and the plugin's own cleanup both do it. Look the player up if you need them, and expect null.
• HomeSetEvent.getLocation() is not necessarily where the player is standing: the set can come from another plugin through setHome(Player, String, Location). getName() is the home's id, not a display name, which is why setting a name a player already used moves that home rather than adding a second.
• BountyClaimEvent carries getKiller(), getVictim(), getAmount() and getBounties(). Every bounty on the victim is collected at once, so getAmount() is the whole pool as a BigDecimal and getBounties() how many placements made it up, at least 1. It fires after the death itself, and only when the victim had a bounty and was killed by a player.
• MineBlockBreakEvent carries getPlayer(), getMineId() and getBlock(), and the block still has the type the player was mining. Inside a mine the server's own BlockBreakEvent is always cancelled, so a listener that ignores cancelled events never sees a mine break — listen to this one instead. It fires again for every block a handler breaks through breakMineBlock, so a handler that does that has to tell its own breaks apart.
• MineResetEvent.getMineId() names the mine. It fires once the last block is back in place, whether the timer, the emptiness threshold or an administrator asked for the reset, and after players buried by the new blocks have been lifted clear. A refill is spread over several ticks, so it arrives a little after the reset began. Only classic mines fire it: a realistic mine grows each block back on its own and is never full again at one moment.
• DuelRoomEndEvent carries getRoomId(), getWinner() and getParticipants(). getWinner() is a nullable UUID, null for a draw — nobody left standing, the fight running out of time, or nobody landing a hit for the room's inactivity limit. getParticipants() is everybody who started the duel in the order they entered, the winner included, some of whom may have left the server: a player who disconnects forfeits but still took part. It fires before the room's rewards reach the winner, and the room stays closed for its loot time afterwards, so the players are usually still inside.
• Every one of them is called on the thread that owns what it is about — the player, or for the two mine events the block and the mine's last refilled block — which on Folia is a region thread rather than a single main thread. DuelRoomEndEvent is called on whichever thread noticed the end: the rooms' once-a-second timer on the global thread, or the region thread of the player whose death, disconnect or exit decided it; neither is guaranteed to own the winner. Anything touching the wider world, or a player the thread does not own, has to be scheduled.

What it does not expose

The plugin runs fifty modules and this service reaches a dozen of them. The rest — portals, regen zones, loot chests, blocked items and the other world-building modules — are administrator tools whose state is a set of placed objects, and there is nothing a third party could usefully do with them. Mines publish their break and their reset and nothing else, so a plugin breaking blocks for a player gets the mine's loot and regeneration instead of a hole.

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 both 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.