API
Ask where a player is, send them into a world, read the worlds and their kits, dress them, read their sandbox statistics, and the join, arrive and leave events.
SandBoxService is how another plugin asks whether a player is in a sandbox or a queue, sends them
into a world, reads the configured worlds and a player's saved kits, dresses somebody in one of them,
and reads their kills, deaths and playtime. Three events tell it when a player asks to come in, lands
and leaves.
ExyliaAPI.get(SandBoxService.class).ifPresent(sandbox -> {
if (sandbox.isInSandbox(player.getUniqueId())) {
event.setCancelled(true);
}
});The artifact, the repository and the plugin.yml line are the same for every Exylia plugin and live
on the public API page.
The claim is the answer, not the world#
isInSandbox answers from the session claim the plugin takes, not from the world the player is
standing in. The two disagree for the length of every unfinished teleport, and the claim wins — which
is what you want: a player who has been claimed and is mid-flight is already busy.
Everything that returns a value reads a cache and is safe from a placeholder, a scoreboard line or a menu redraw. Everything that acts teleports players and rewrites inventories: call those on the main thread, and no more often than a player could trigger them.
Session#
| Method | What it does |
|---|---|
boolean isInSandbox(UUID) | Whether they hold the sandbox claim. |
boolean isInQueue(UUID) | Whether they are waiting for an opponent. |
boolean leave(Player) | Sends them back to the lobby. Reports whether the request was accepted, not whether it finished; false while they are building a kit. |
boolean joinQueue(Player, String worldId, int kitSlot) | Queues them for one world. false only when no world is configured under that id — anything else the queue refuses is said to the player. |
void leaveQueue(Player) | Takes them out of whichever queue they are in. |
EnterResult enter(Player, String worldId, int kitSlot) | Sends them straight into a world, dressed in one of their kits — the /rtp way in. |
void openWorldSelector(Player) | Opens the world list /rtp opens: the screen a lobby NPC wants. |
enter decides every refusal before anything is taken from the player, and says none of them to the
player: the result is yours to put into words. ACCEPTED is a request under way, not an arrival —
finding a safe spot and landing the teleport end some ticks later and can still fail, in which case the
player is given back as they were and told so. SandboxArriveEvent is the confirmation.
EnterResult | Meaning |
|---|---|
ACCEPTED | On their way in |
BUSY | Another plugin holds them, or they are building a kit |
ALREADY_IN_SANDBOX | Moving between sandbox worlds is not entering one |
UNKNOWN_WORLD | No world is configured under that id |
WORLD_NOT_READY | Still generating, or unavailable |
NO_KIT | The slot holds no saved kit with anything in it |
REFUSED | A SandboxJoinEvent handler cancelled it, the player is combat-tagged (they are told general.in-combat), or another plugin took them between the checks and the claim |
openWorldSelector opens whether or not the player could enter right now: a world that is not ready
draws without an action, and every way in the screen offers makes its own checks when clicked.
Worlds#
| Method | What it does |
|---|---|
List<SandboxWorld> worlds() | Every configured world, unusable ones included, in no particular order. Unmodifiable. |
Optional<SandboxWorld> world(String worldId) | One by id. |
Optional<SandboxWorld> worldOf(World) | The listener's question: is this Bukkit world one of ours? |
float pregenerationProgress(String worldId) | 0 to 1. 0 for a world that has finished as well as one that never started. |
SandboxWorld is a snapshot, not a live view: id, displayName, worldName, biome, borderSize,
type, status and loaded, plus isPlayable() — loaded and READY. It carries a world name
rather than a World because a configured world is not necessarily loaded.
WorldStatus is CREATING, PREGENERATING, READY or UNAVAILABLE. WorldType is MANAGED or
IMPORTED.
Kits#
| Method | What it does |
|---|---|
List<SandboxKit> kits(UUID) | Their saved kits, ordered by slot. An offline player reports nothing. Unmodifiable. |
Optional<SandboxKit> kit(UUID, int slot) | One slot. |
Optional<SandboxKit> favoriteKit(UUID) | The starred one, if they have one. |
int maxKits(Player) | How many slots they are allowed. Reads permissions, so it takes the player. |
int activeKitSlot(UUID) | The slot they are wearing, -1 when they are wearing none. |
void applyKit(Player, int slot) | Replaces what they carry with that kit. A no-op on an unused slot. |
SandboxKit is slot, name, favorite, hasContents, createdAt and updatedAt. The contents
are deliberately not exposed — use applyKit rather than reading the stacks.
Statistics#
| Method | What it does |
|---|---|
SandboxStats stats(UUID) | Never empty. A player nothing has loaded reads as zeroes, and the read is started, so the next draw has the numbers. |
SandboxStats is player, kills, deaths and playtimeMillis, plus kdr() — which returns the
kill count when there are no deaths. Playtime is sandbox time only, not time on the server.
Events#
All three live in net.exylia.lib.api.sandbox.event, carry getPlayer() and getWorld() (a
SandboxWorld), and are called on the thread that owns the player, which on Folia is their region
thread.
| Event | When | Cancellable |
|---|---|---|
SandboxJoinEvent | A player asks for a world, by random teleport or by joining its queue, before anything is taken from them. getKitSlot() and isQueued() say how. | Yes: they are left exactly as they were, and the plugin says nothing |
SandboxArriveEvent | They have landed, in survival with full health and their kit on. The confirmation the other two are not. | No |
SandboxLeaveEvent | The sandbox has let go of them: inventory back, claim released. getReason() is LEFT, DIED or DISCONNECTED. | No |
A queue asks once, when the player joins it, not again when a partner is found — refusing then would
send the partner in alone. Moving from one sandbox world to another fires none of the three, and
neither does logging back in inside one. Leaving a queue, or a way in that failed before the player
arrived, does not fire SandboxLeaveEvent. Cancelling a join says nothing to the player: telling them
why is the canceller's job.
Something missing on this page? Tell us on Discord